forge-connector

Name: forge-connector
Author: atlassian

144installs8forks

How to install forge-connector?

atlassian/forge-skills/forge-connector

$npx -y skills add atlassian/forge-skills --skill forge-connector

Installs into the current project.

Summary

Guides building and deploying Atlassian Forge Teamwork Graph connector apps that ingest external data into Atlassian's Teamwork Graph, making it searchable in Rovo Search and surfaced in Rovo Chat. Use when the user wants to build a Forge connector, ingest external data into Atla

Files · 1

View on GitHub

SKILL.md

1	# Forge Connector
2
3	Builds a `graph:connector` Forge app that ingests external data into Atlassian's Teamwork Graph so it appears in Rovo Search and Rovo Chat.
4
5	## Critical Rules
6
7	1. Must install in Jira — Apps using Teamwork Graph modules must be installed on a Jira site. Confluence-only installs will not work.
8	2. Never ask for credentials in chat — Direct users to run `forge login` in their own terminal.
9	3. Always run the scaffold script yourself — Do not only give manual instructions; run `scripts/scaffold_connector.py` to generate the boilerplate.
10	4. Always ask the user for their Atlassian site URL when install is needed — never discover or guess it.
11	5. Atlassian deletes data on disconnect — When `action = 'DELETED'`, the app only needs to clean up local state; Atlassian removes the Teamwork Graph data automatically.
12	6. Handler arguments are passed directly — Forge passes the request object as the first argument to handlers, NOT nested under `event.payload`. Config values are at `request.configProperties`, NOT `event.payload.config`. This is the most common source of `TypeError: Cannot destructure property of undefined` errors.
13	7. Use `@forge/kvs` for storage — Import `kvs` from `@forge/kvs`. Do NOT use `@forge/storage` — its `storage` export is `undefined` at runtime in connector functions.
14	8. Use `graph` named export from `@forge/teamwork-graph` — The correct import is `const { graph } = require('@forge/teamwork-graph')`. Call `graph.setObjects({ objects, connectionId })`. Do NOT import `setObjects` as a named export directly.
15	9. `validateConnectionHandler` must return `{ success, message }` — Do NOT throw an Error. Return `{ success: false, message: '...' }` to reject, `{ success: true }` to accept.
16	10. `function` declarations belong under `modules` — In `manifest.yml`, `function:` is a key under `modules:`, not a top-level key. Placing it at the top level causes a lint error.
17	11. `formConfiguration` uses `form` array with `type: header` — Do NOT use `fields:` or `beforeYouBegin:`. The correct format uses `form: [{ key, type: header, title, description, properties: [...] }]`.
18	12. Scopes are `read/write/delete:object:jira` — Use `read:object:jira`, `write:object:jira`, `delete:object:jira`. The scopes `read:graph:teamwork` and `write:graph:teamwork` are invalid and will fail `forge lint`.
19	13. Set `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector` on `forge` commands run for this skill — prefix `forge` invocations with this env var: ones you run in the shell (e.g. `forge lint`, `forge logs`, `forge deploy`) and the interactive `forge create` command you hand the user as a fallback. The bundled scripts set it automatically; other commands shown in this skill omit it for brevity — add it when you run them. The only exclusions are `forge login` and `forge tunnel` (user-run auth / live-dev commands).
20
21	## MCP Prerequisites
22
23
24	\| MCP Server \| Purpose \|
25	\| ------------- \| ------------------------------------------------- \|
26	\| Forge MCP \| Manifest syntax, module config, deployment guides \|
27	\| ADS MCP \| Atlaskit components (only if adding Custom UI) \|
28
29
30	---
31
32	## Agent Workflow — Complete Steps 0–7 in Order
33
34	### Step 0: Prerequisites
35
36	Check Node.js (`node -v`, requires 22+), Forge CLI (`forge --version`), and login (`forge whoami`). Install missing tools:
37
38	```bash
39	npm install -g @forge/cli
40	```
41
42	Tell the user to run `forge login` in their terminal if not authenticated.
43
44	### Step 1: Discover Developer Spaces
45
46	> Note: `forge developer-spaces list` does NOT exist in Forge CLI 12.x. You cannot list developer spaces non-interactively.
47
48	`forge create` requires an interactive TTY to select a developer space. Ask the user to run it themselves:
49
50	```
51	Tell the user:
52	cd <parent-directory>
53	ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector forge create --template blank <app-name>
54
55	When prompted, select a Developer Space and let it complete.
56	Come back when done.
57	```
58
59	The `--dev-space-id` flag in the scaffold script is optional and can be omitted — the script has been updated to skip it when not provided.
60
61	### Step 1.5: Discover Data & Map to Object Types
62
63	**Do this befor

People who liked this also viewed

6 picks

Type

forge-connector

144installs8forks

View on GitHub

How to install forge-connector?

atlassian/forge-skills/forge-connector

$npx -y skills add atlassian/forge-skills --skill forge-connector

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Forge Connector
2
3	Builds a `graph:connector` Forge app that ingests external data into Atlassian's Teamwork Graph so it appears in Rovo Search and Rovo Chat.
4
5	## Critical Rules
6
7	1. Must install in Jira — Apps using Teamwork Graph modules must be installed on a Jira site. Confluence-only installs will not work.
8	2. Never ask for credentials in chat — Direct users to run `forge login` in their own terminal.
9	3. Always run the scaffold script yourself — Do not only give manual instructions; run `scripts/scaffold_connector.py` to generate the boilerplate.
10	4. Always ask the user for their Atlassian site URL when install is needed — never discover or guess it.
11	5. Atlassian deletes data on disconnect — When `action = 'DELETED'`, the app only needs to clean up local state; Atlassian removes the Teamwork Graph data automatically.
12	6. Handler arguments are passed directly — Forge passes the request object as the first argument to handlers, NOT nested under `event.payload`. Config values are at `request.configProperties`, NOT `event.payload.config`. This is the most common source of `TypeError: Cannot destructure property of undefined` errors.
13	7. Use `@forge/kvs` for storage — Import `kvs` from `@forge/kvs`. Do NOT use `@forge/storage` — its `storage` export is `undefined` at runtime in connector functions.
14	8. Use `graph` named export from `@forge/teamwork-graph` — The correct import is `const { graph } = require('@forge/teamwork-graph')`. Call `graph.setObjects({ objects, connectionId })`. Do NOT import `setObjects` as a named export directly.
15	9. `validateConnectionHandler` must return `{ success, message }` — Do NOT throw an Error. Return `{ success: false, message: '...' }` to reject, `{ success: true }` to accept.
16	10. `function` declarations belong under `modules` — In `manifest.yml`, `function:` is a key under `modules:`, not a top-level key. Placing it at the top level causes a lint error.
17	11. `formConfiguration` uses `form` array with `type: header` — Do NOT use `fields:` or `beforeYouBegin:`. The correct format uses `form: [{ key, type: header, title, description, properties: [...] }]`.
18	12. Scopes are `read/write/delete:object:jira` — Use `read:object:jira`, `write:object:jira`, `delete:object:jira`. The scopes `read:graph:teamwork` and `write:graph:teamwork` are invalid and will fail `forge lint`.
19	13. Set `ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector` on `forge` commands run for this skill — prefix `forge` invocations with this env var: ones you run in the shell (e.g. `forge lint`, `forge logs`, `forge deploy`) and the interactive `forge create` command you hand the user as a fallback. The bundled scripts set it automatically; other commands shown in this skill omit it for brevity — add it when you run them. The only exclusions are `forge login` and `forge tunnel` (user-run auth / live-dev commands).
20
21	## MCP Prerequisites
22
23
24	\| MCP Server \| Purpose \|
25	\| ------------- \| ------------------------------------------------- \|
26	\| Forge MCP \| Manifest syntax, module config, deployment guides \|
27	\| ADS MCP \| Atlaskit components (only if adding Custom UI) \|
28
29
30	---
31
32	## Agent Workflow — Complete Steps 0–7 in Order
33
34	### Step 0: Prerequisites
35
36	Check Node.js (`node -v`, requires 22+), Forge CLI (`forge --version`), and login (`forge whoami`). Install missing tools:
37
38	```bash
39	npm install -g @forge/cli
40	```
41
42	Tell the user to run `forge login` in their terminal if not authenticated.
43
44	### Step 1: Discover Developer Spaces
45
46	> Note: `forge developer-spaces list` does NOT exist in Forge CLI 12.x. You cannot list developer spaces non-interactively.
47
48	`forge create` requires an interactive TTY to select a developer space. Ask the user to run it themselves:
49
50	```
51	Tell the user:
52	cd <parent-directory>
53	ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-connector forge create --template blank <app-name>
54
55	When prompted, select a Developer Space and let it complete.
56	Come back when done.
57	```
58
59	The `--dev-space-id` flag in the scaffold script is optional and can be omitted — the script has been updated to skip it when not provided.
60
61	### Step 1.5: Discover Data & Map to Object Types
62
63	**Do this befor

People who liked this also viewed

6 picks

Type