Connect JIRA#

Difficulty: moderate (API token). Sync JIRA issues in and out, scoped to a project.

Auth at a glance#

What you'll need#

• Your Atlassian account email.
• An API token (Atlassian account → Security → API tokens).
• Your JIRA site URL (https://yourco.atlassian.net) and a project key you can create issues in (e.g. ENG).

Steps#

1. Create an API token in your Atlassian account settings.
2. In Connections, choose JIRA → Connect. Enter your email + token and the site URL + project key.
3. Forge stores the token encrypted and verifies the connection.

What you get#

• Source: JIRA's search API is the change feed — Forge polls updated > <cursor> and emits one change per issue, keyed on the issue key.
• Destination: create/update issues, upserted by an external id.

Gotchas#

• JIRA has no native upsert. Forge synthesizes one: it stamps a label forge-eid-<external_id> on the issue and keys writes on a JQL label search. That search index is eventually consistent — a just-created issue may not be found for a few seconds, so read-after-write briefly lags (Forge retries).
• Issue type. New issues default to Task unless you map an issuetype field — make sure that type exists in the project's scheme.
• Delete needs a permission. Deleting an issue requires the "Delete issues" project permission. Without it JIRA returns 403 and Forge surfaces it as a permanent error rather than swallowing it — grant the permission first.
• Auth errors are permanent. A wrong email/token or missing project access returns 401/403; Forge aborts rather than retrying against JIRA's auth (which could trip a lockout). Re-check the pair, don't just re-run.

What Forge provisions for you#

You still create the API token (Atlassian requires a human for that), but Forge handles all of the upsert-by-external-id machinery JIRA lacks natively — the label stamping, the JQL search, the search-index retry, and the delete-by-key confirmation.