Jira

The Jira integration connects codev to your Atlassian Jira site so that the work items referenced in your commits are visible throughout your delivery pipeline — and, optionally, so that codev reports deployment and build status back to the matching Jira issues.

You configure it under Settings > Organization > Integrations > Jira. Only organization owners can save or remove its credentials; anyone who can open the page can run Test.

What the Jira integration does

The integration works in two directions: reading work items, and, optionally, writing deployment and build status back. Atlassian issues a different credential for each direction, and no single Jira credential does both.

codev never edits your issues directly. To move an issue's status when it is deployed, drive a Jira Automation rule from the deployment data codev writes back.

Credentials

The Jira page asks for your Jira site once and shows one card for each job codev does with Jira. Each card holds its own credential.

To read work items and write status back, fill in both cards. A credential that can do both jobs is entered in both cards.

You bring your own Jira

Unlike GitHub on the cloud instance, there is no flxbl-managed Jira connection. Jira is always something your organization connects itself — on both the cloud and self-hosted instances. Until you register a Jira integration, work items are not read and nothing is written back.

Adding the integration

1. Go to Settings > Organization > Integrations > Jira.
2. Enter your Jira site (https://your-site.atlassian.net). Both credentials come from this site.
3. On the Read work items card, enter the Client ID and Client Secret of a service account's OAuth credential (see Reading with a service account). To use an API token instead, select Use an API token instead (Atlassian email + API token) and enter your Atlassian email and an API token created at Atlassian Account Settings > Security > API tokens.
4. To write status back, enter the Client ID and Client Secret of a Jira-admin OAuth credential on the Send deployments and builds card (see Creating the write-back credential).
5. Under Availability, choose Global (all projects), optionally marked the default for Jira, or a Specific project. Availability applies to both credentials. The panel opens on the saved credential's current Availability. To move a saved credential to another scope, enter its secret again and select Save.
6. Select Test on a card to check its credential, then Save.

Each card shows its state: Not connected until its credential is saved, Connected once it is, and Needs attention after a test that did not pass. A connected card has Edit credentials and Delete actions next to its state.

What Test checks

Test checks the credential in the card's fields without saving it. On a connected card whose fields are unchanged, it checks the saved credential. It requests a token exactly as codev does at runtime, then:

• Read work items reads one issue the credential can see and names it, for example Tested just now: read DP-10 from your-site.atlassian.net.
• Send deployments and builds submits one deployment and one build linked only to CODEVTEST-0, an issue key that can never exist. Jira authorizes them like real data and, because they belong to no known issue, does not store them. When Jira accepts both and reports that key as unknown, the card shows Tested just now: Jira accepts this credential for deployments and builds.

A saved API token is only sent to its saved Jira site. To test it against another site, enter the API token again.

When Jira refuses the credential, the card turns Needs attention and shows Atlassian's reason and how to fix it. A result that proves less than the job, such as a credential that can see no issues, says only what was proven.

Reading with a service account

An Atlassian service account is an account that does not belong to a person. Its OAuth 2.0 credential reads issues without a personal API token. An organization admin creates it in Atlassian Administration (admin.atlassian.com); Atlassian describes the steps in Create an OAuth 2.0 credential for a service account.

1. In your organization, go to Directory > Service accounts and select Create a service account.
2. Give it a name and, on the app roles step, the User role on your Jira site.
3. Open the service account, select Create credentials, and choose OAuth 2.0.
4. Name the credential and select the scopes read:jira-work and read:jira-user.
5. Copy the Client ID and Client Secret into the Read work items card. Atlassian shows the secret only once.

The service account reads only the projects it can browse in Jira.

This credential cannot write back. Jira rejects its deployment and build data with 403 (Provider '<client id>' not installed), even with the write:deployment-info:jira and write:build-info:jira scopes, because only a Jira site OAuth credential or an installed Jira app can send that data.

Creating the write-back credential

Write-back authenticates to Jira's DevOps APIs (Deployments and Builds) with a Jira site OAuth credential. A Jira site admin creates it in Jira — not in the Atlassian Developer Console, and not as a service account.

1. In Jira, open the settings gear (top right) > Apps, then OAuth credentials in the left sidebar. The direct URL is https://your-domain.atlassian.net/secure/admin/oauth-credentials — the /jira/settings/... routes do not reach this page.
2. Select Create new credentials.
3. Give it a name and a Server base URL (your codev instance URL), and grant both the Deployments and Builds permissions. Both are required; a credential missing either one is accepted on this page but rejected when codev writes.
4. Copy the generated Client ID and Client Secret into the Send deployments and builds card.

Scope

Availability applies to each credential when you select Save on its card. codev chooses the read and write-back credentials separately for each project: the project's credential first, then that job's default, then a global credential. The read and write-back credentials can each have their own default.

A credential scoped to one project does not serve other projects. A project that overrides only one job keeps the global credential for the other job. If no credential is available for a job, codev tries the other job's OAuth credential; Jira can refuse it because the two credential types grant different capabilities.

Showing work items

Once a Read work items credential is saved, codev extracts Jira issue keys from your commit messages (for example, DP-123 or [PROJ-456]) and surfaces them where you plan and ship. For the full set of recognised commit-message formats — and a common pitfall, since an issue key in round parentheses is not detected — see Work items. Detected keys are surfaced:

• On a release candidate, in its Work items and Cumulative changes sections.
• In the release request flow, as Indicative Work Items, so you can see which issues a release will deploy and whether the deployment is full or partial.
• On a release opened from an environment, in its Work items section. It shows the first five; View all opens the release's details.

Each issue shows its key and summary, and under them its Jira status and assignee. The status badge is coloured by the status's category in Jira: grey for To Do, blue for In Progress, green for Done. An issue with no assignee reads Unassigned. Select the issue to open it in Jira. A change made in Jira shows the next time the view loads, at most a minute later.

Without a Read work items credential, the keys are listed without their summary, status or assignee. If Jira refuses the saved credential, each issue reads Work item details unavailable with a Retry link — see Troubleshooting.

How keys are detected and linked is part of each project's configuration:

Writing status back to Jira

Write-back is optional. It is active for a project only when both conditions are met:

• A Send deployments and builds credential is saved, and
• Write-back is enabled in the project's configuration.

When active, codev reports to Jira as your pipeline runs:

codev maps your environments to Jira's environment types — review and dev environments as development, test and snapshot as testing, and release as staging.

Troubleshooting

Issue keys appear, but their summary, status and assignee never load. The Read work items card is Not connected, so codev reads issues with the Send deployments and builds credential, and Jira refuses the reads with 401 (Unauthorized; scope does not match). Save a service account's OAuth credential or an API token on the Read work items card, then select Test.

Work items read Work item details unavailable, or reading issues fails with an error that Jira refused the OAuth credential. Atlassian rejected the token request for the Read work items credential. Select Test on the card: it shows Atlassian's reason. The usual cause is a credential that is not a service account's OAuth 2.0 credential — see Reading with a service account.

Deployments and builds don't appear, and Test reports Jira refused the credential with 403. The Send deployments and builds card holds a service account's credential. Jira answers its deployment and build data with Provider '<client id>' not installed, since it accepts that data only from a Jira-admin OAuth credential or an installed Jira app. Replace it with a Jira-admin OAuth credential — see Creating the write-back credential.

Deployments and builds don't appear in Jira. The usual causes:

• The credential is a Developer Console (three-legged) OAuth app rather than the site OAuth credentials (client-credentials) app. Atlassian refuses to issue it a token — the token request fails with 400 (invalid_client, grant_type is not enabled for client) — so nothing is sent to Jira. Create a credential on the OAuth credentials page — see Creating the write-back credential — and enter its Client ID and Client Secret on the Send deployments and builds card.
• The OAuth credential is missing the Deployments or Builds permission. A token is issued, but Jira rejects the write. Re-open it at Settings > Apps > OAuth credentials, confirm both are granted, and — if you recreate it — enter the new Client ID and Client Secret on the Send deployments and builds card. Test names the API Jira refused.
• Write-back is registered but not enabled for the project, so codev sends nothing to Jira — see Writing status back to Jira.

A deployment or build doesn't show on an individual issue. Jira indexes this data asynchronously. Confirm it arrived on the project-level Development > Deployments view, which updates before the per-issue panels.

A referenced issue key isn't detected. Check the project's jiraProjects and workItemRegexFilter settings, and note that a key inside round parentheses is not detected — see Work items.

Self-hosting

Both cards work the same on a self-hosted instance, with the same Cloud-only restriction on OAuth. Server-level configuration is covered in the sfp server documentation.

---

Once a Read work items credential is saved, see how detected issue keys appear across your pipeline.