Bitrise for Jira app
The Bitrise for Jira app surfaces your Bitrise build and pipeline statuses directly on Jira issues, so your team can see where work stands without leaving Jira.
The Bitrise for Jira app works with Jira Cloud only: it doesn't support self-hosted Jira (Jira Data Center or Jira Server).
Build information appears on a Jira issue in two places:
-
A dedicated Bitrise builds section, where you can also re-run or abort a build.
-
The Builds tab of Jira's standard development panel.
Build information only appears on a Jira issue when the issue key (for example, PROJ-123) is present in at least one of the following:
- The branch name.
- A Git tag.
- The pull request title.
- The pull request description.
- A commit message.
Setting up the app has two sides:
- On Jira: a Jira admin installs the app and completes the connection.
- On Bitrise: a user who can create the token and has Platform Engineer (or Admin) access on the relevant projects decides which projects to connect. See Creating a token for why that access level is required.
This page walks through both sides from start to finish. Each section names who's responsible.
Setup at a glanceClick to copy link
| Task | Done on |
|---|---|
| Installing the app in Jira | Jira, by a Jira admin |
| Creating a token | Bitrise, by whoever creates the token |
| Connecting Bitrise projects | Bitrise, then Jira |
| Verifying the connection | Jira, by a Jira admin |
Installing the app in JiraClick to copy link
You need permission to install and configure apps on the Jira site.
- In Jira, go to Apps > Explore more apps and search for Bitrise for Jira.
- Select the app and click Get it now to install it.
If you're not a Jira admin, use Request to install to send an approval request to your admin instead.
Creating a tokenClick to copy link
The app authenticates to Bitrise with an API token, either a workspace API token or a Personal access token. Who can create one, and what access it needs, depends on the type:
| Workspace API token | Personal access token | |
|---|---|---|
| Belongs to | The workspace | An individual user |
| Scope | A single workspace; can be limited to specific projects | Everything the user can access, across all their workspaces |
| Who can create it | A workspace owner, or a member with the Manager workspace role | Any user, for their own account |
| Needed on each connected project | Platform Engineer as the token's Bitrise CI product-access role | Platform Engineer (or higher) as the token owner's own project role |
| Survives people leaving | Yes | No — the connection breaks if the user loses access |
| Recommended for | Most setups | Connecting apps that span more than one Workspace |
Use a Workspace API token. It's tied to the Workspace rather than a person, can be scoped to just the Bitrise projects you want to connect to the app, and doesn't break when someone leaves the team. Choose a Personal access token only if you need to connect projects from more than one Workspace.
On each connected project, the app registers an outgoing webhook (needs the change_settings permission) and re-runs or aborts builds (needs run_builds). Platform Engineer is the lowest Bitrise CI role that covers both: Admin and Owner also work, but Developer and Tester/QA don't have enough access.
- For a Personal access token, this is the token owner's own role on the project.
- For a Workspace API token, this is the Bitrise CI product access role you set on the token. The Workspace role (Viewer, Contributor, Manager) is separate: it only controls who can manage the token, not what the app can do on connected projects.
- Workspace API token
- Personal access token
-
Log in to Bitrise and hover over the left navigation bar.
-
Make sure you have the right workspace selected in the Workspace menu.
-
Select Settings.
-
On the left, select Security.
-
Click Create token and follow Creating a Workspace API token, with these settings:
- Set the Workspace role to Manager (this controls who can manage the token, not what the app can do).
- Under Configure access to products, toggle Bitrise CI on and set its role to Platform Engineer: this is the access the app actually uses on connected projects.
- Choose whether the token applies to all projects or only selected ones.
- Create a personal access token.
- Make sure your own account has at least Platform Engineer role on every project you want to connect.
You can only view a token's value at the moment you create it. Copy it and store it securely before leaving the Save token step.
You can set the token to never expire. If you set an expiry, the Jira connection stops working when the token expires: Maintaining the connection.
Connecting Bitrise projectsClick to copy link
To connect Bitrise projects to Jira, you need the API token and a list of the projects you want to connect. The connection is completed on the Jira side, so a Jira admin must do that part.
- On Bitrise: Decide which Bitrise projects should send updates to Jira. Make a list of the specific projects, or decide to connect all of them.
- Share the API token and the project list with the Jira admin through a secure channel, such as a password manager or secrets tool, not over plain email or chat.
- On Jira: Go to Apps > Manage your apps > Bitrise for Jira and open its configuration page.
- Under Bitrise API Token, paste the token you received and click Save.
- Under Connected Bitrise Projects, select the projects you were given and click Save.
An outgoing webhook is created automatically in Bitrise for each connected project. You don't need to configure webhooks manually.
Verifying the connectionClick to copy link
You can verify the connection with a Jira admin.
- Open a Jira issue whose key appears in the branch name, a Git tag, the pull request title, the pull request description, or a commit message of work in a connected Bitrise project.
- Confirm that Bitrise build status appears in the Bitrise builds section of the issue and in the Builds tab of the development panel.
If nothing appears, see Troubleshooting.
Maintaining the connectionClick to copy link
- Token expiry or change: If the API token expires, is regenerated, or is replaced, the connection stops working. Update the token on the app's configuration page and re-check your connected projects.
- New Bitrise projects: When you add a new project in Bitrise that you want to appear in Jira, return to the app's configuration page and add it under Connected Bitrise Projects.
TroubleshootingClick to copy link
- No build status on issues: Confirm the issue key is present in the branch name, a Git tag, the pull request title, the pull request description, or a commit message. Then check that the token is still valid and that the relevant project is selected under Connected Bitrise Projects.
- A project is missing from the list: The token can't access it. Check that the token (or the project role of its owner, for a Personal access token) includes that project, or ask whoever created the token to update it.
- Build status that used to work stops appearing: The usual cause is someone unchecking Attach Bitrise OIDC token on the connected project's outgoing webhook, in Bitrise. Check the Activity section on the app's Jira configuration page for rejected deliveries.