How to track deployments in Jira from any CI pipeline
By Jake Marsh · Updated
To track deployments in Jira from a pipeline that has no Jira integration, add one HTTP call to its deploy step. With Berth, create a CI token in Jira settings > Apps > Berth > CI tokens, store it as a secret, and POST the environment key, version and state to Berth's endpoint after each deploy. Work item keys in your commit messages are picked up, so each environment shows its current version and the work items on it, and every work item shows where it's deployed.
The call
curl -sS -X POST "$BERTH_URL" \
-H "Authorization: Bearer $BERTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"environment": "staging-2", "version": "4.2.0", "state": "successful",
"commits": ["SHOP-142 fix rounding", "SHOP-150 wishlist"],
"pipeline": "GitHub Actions", "url": "https://github.com/acme/shop/actions/runs/123"}'
environment and version are required. Everything else is optional:
| Field | What it's for |
|---|---|
state | successful (default), failed, in_progress, pending, rolled_back or cancelled |
issueKeys | Work item keys, as a list or comma-separated text |
commits | Commit messages; keys in them are picked up |
branch, description | Keys in these are picked up too |
pipeline, url, pipelineUrl, commit | Shown on the environment page; url links the version |
at | When it happened, if within a day of now |
Steps
- Add the environment in Jira settings > Apps > Berth > Environments, with the key your pipeline will send, such as
staging-2. - Create a token under CI tokens > New token, named after the pipeline. Limit it to some environments if you want. Copy it now; Berth keeps only a hash.
- Store it in your CI as a secret named
BERTH_TOKEN, and the endpoint asBERTH_URL. - Test it. A
GETto the endpoint with the token answers which environments the token may report to. - Add the POST to the end of the deploy step. Send
in_progressat the start too if you want the board to show "deploying". - Read the reply. It lists the keys recorded, the keys ignored (their space doesn't exist on the site), and what happened with Jira's Deployments panel.
What each state does
| State | On the board |
|---|---|
| successful | The version becomes current, and its work items are on the environment from this version |
| in_progress, pending | "deploying", for up to 2 hours |
| failed | "last deploy failed"; the current version stays |
| rolled_back | The work item keys you send are taken off the environment |
Seeing the result
- The board: each environment's current version and status.
- An environment's page: Work items on it, with status and the version each arrived in, plus Not yet on, which compares it with another environment. Pick production to list everything on staging that hasn't shipped.
- A work item's Environments (Berth) panel: where it is, since which version, and which production environments don't have it yet.
Jira's own Deployments panel too
Jira's Deployments panel and Releases hub are filled by connected CI tools. Turn on the setting in Berth to pass the deployments you report on to Jira's Deployments panel as well, so pipelines Jira has no integration for show up there next to the rest.
Berth starts with Atlassian's 30-day free trial; prices are on the Berth page. To let people reserve the same environments, see how to book shared test environments in Jira.
What it costs
Berth is From $19 a month for up to 10 users. Every plan and the install link are on the Berth page.
Berth: Environment Booking and Deployment Tracking
Book shared test environments in Jira without clashes, and see which build and which work items are on each one, from any CI. From $19 a month for up to 10 users.
Questions
Does this work with Jenkins, GitLab CI or Azure Pipelines?
Yes. Anything that can send an HTTP POST with a header works, including a plain shell step.
Do I have to put work item keys in commit messages?
It's the easiest way, since keys in commits, the branch or the description are picked up. You can also send them in issueKeys.
Can one token report to every environment?
Yes, unless you limit it. One token per pipeline makes it easy to see where each deployment came from.
Does Berth connect to our CI servers?
No. Pipelines call Berth; Berth never calls out.
More Berth guides
More Jira guides
- How to set up a release notes template in Jira (Changeleaf)
- How to bulk delete attachments in Jira Cloud (Attachwell)
- How to set up a code freeze in Jira (Cutline)
- How to find duplicate issues in Jira (Mergewell)