Jira Cloud connection#
A Jira Cloud connection stores credentials and scope for one Jira project. OakCore uses it to bind issues from that project to specification nodes — see Jira issues.
One connection per Jira project#
Same pattern as GitHub: one connection = one scope. Multiple Jira projects on one OakCore project → multiple connections. You may reuse the same API token across connections if it has access to all target projects.
Before you start#
- Open your project in OakCore and go to Settings → Integrations.
- Add one connection per target Jira project.
- In Jira, for issue bindings you need:
- A dedicated URL custom field on the issue screen for OakCore backlinks (the field's display name, e.g.
OakCore link). OakCore leaves existing field values untouched and uses a managed comment when the field is already in use. - Permission to read and edit issues in the target project (backlinks).
- Admin access on the Jira project to configure webhooks (recommended).
Add a connection#
In Settings → Integrations, click Add → Jira Cloud project.
Label#
A short name only used inside OakCore so you can tell connections apart.
| Good | Avoid |
|---|---|
Platform backlog |
PROJ (that is the project key) |
Customer portal bugs |
jira |
Sprint team A |
https://acme.atlassian.net |
This label appears when you pick a connection while binding an issue to a node.
Site URL#
Your Jira Cloud base URL — origin only, no paths.
For https://acme.atlassian.net/jira/software/projects/PROJ/boards/1, enter https://acme.atlassian.net.
Must use https://.
Project key#
The short project prefix on issue keys — e.g. PROJ in PROJ-42.
Only issues from this project can be bound through this connection.
Account email#
The Atlassian account email used with the API token. Jira Cloud REST API uses Basic authentication with {email}:{api_token}.
Backlink field#
Name or id of a dedicated URL custom field where OakCore can write the landing link. System fields and other custom-field types are not supported.
Enter the display name of your URL custom field (e.g. OakCore link). OakCore resolves it to the technical id when you save or click Test — you do not need to look up customfield_… yourself.
The field must be on the issue Edit / View screen for the target project.
API token#
An Atlassian API token OakCore uses to call Jira on your behalf. It is stored encrypted and cannot be viewed again after you save — only replaced.
- Go to Atlassian account security → API tokens.
- Create API token, copy once, paste into OakCore.
The account must be able to browse and edit issues in the configured project, and add comments (fallback backlink when the custom field cannot be updated).
Webhook secret (optional in the form, required for webhooks)#
A shared password sent by Jira Automation in the X-OakCore-Webhook-Secret request header. OakCore verifies incoming Jira updates against this value.
- Leave empty if you are only testing binds and manual refresh — syncing still works via polling, but live updates will be delayed.
- Set a secret if you configure a Jira webhook (recommended for production).
openssl rand -hex 32
Use the same value in the Jira Automation rule's X-OakCore-Webhook-Secret request header.
Editing an existing connection
Token and webhook secret fields are blank when editing. Leave them empty to keep current values, or enter new values to rotate them.
Test the connection#
After saving, click Test on the connection card. OakCore checks that the token can reach the configured Jira project.
Configure the Jira webhook (recommended)#
Webhooks push updates to OakCore within seconds. Without them, OakCore still refreshes on a schedule, but Jira changes may appear later.
In Jira, create an Automation rule that sends a web request when an issue is updated or deleted.
| Field | Value |
|---|---|
| URL | Copy from the connection card in Settings → Integrations |
| Header | X-OakCore-Webhook-Secret: {webhook_secret} |
| Triggers | Issue updated, Issue deleted |
The URL must use your OakCore API host (serves /api/v1/...), reachable from Atlassian over the public internet.
Multiple projects#
Each Jira project needs its own connection. When binding, pick the connection that matches the issue's project.
Troubleshooting#
| Symptom | What to check |
|---|---|
| Test fails | Site URL, project key, or email typos; token expired; account lacks project access |
| Bind rejected | Issue key belongs to a different project than the selected connection |
| No backlink on issue | Backlink field display name; field on issue screen; token can edit issues |
| Jira changes not reflected | Automation rule sends the correct X-OakCore-Webhook-Secret; triggers selected; API URL reachable |
For self-hosted OakCore deployments, ensure Atlassian can reach your API URL.