Berth documentation (public knowledge base source)
Get started (Jira admin, 10 minutes)
- Jira settings > Apps > Berth > Environments > Add environment. For each environment people
share or deploy to: a name, the short key your CI will send (suggested from the name, for
example
staging-2), the tier (development, testing, staging, production, other), a group (for example the product or team), its URL, an owner, whether it can be booked, and the longest booking in hours. Production is not bookable by default. - CI tokens > New token. Name it after the pipeline ("GitHub Actions, shop") and, if you
like, limit it to some environments. Copy the token right away: Berth keeps only a hash.
Store it in your CI as a secret (for example
BERTH_TOKEN), and the endpoint asBERTH_URL. - Settings. Pick the time zone for booking times, the first day of the week, who can book (everyone or one Jira group; Jira admins always can), how far ahead, and whether deployments should also appear in Jira's own Deployments panel.
Book an environment
Apps > Environments > Book an environment (or Book on a row). Pick the environment, start now or at a date and time, the end, what it is for, and optionally a work item. If someone already has it, Berth says who and until when, lists environments of the same tier that are free for the whole time, and says when this one is free next.
- My bookings: change the end, end now, or cancel a future booking.
- Owners and Jira admins can end anyone's booking on their environment (environment page, Bookings tab). The activity log says who did it.
- Week shows every booking for the week; your own bookings are highlighted.
Report deployments from CI
POST JSON to the endpoint with Authorization: Bearer <token>:
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"}'
| Field | Required | Notes |
|---|---|---|
environment | yes | The environment key |
version | yes | Version, tag or build number |
state | no | successful (default), failed, in_progress, pending, rolled_back, cancelled. Also accepts success, failure, running, canceled |
issueKeys | no | List (or comma-separated text) of work item keys in this deployment |
commits | no | Commit messages (or { "message": ... } objects); keys in them are picked up |
branch, description | no | Keys in them are picked up too |
pipeline, url, pipelineUrl, commit | no | Shown on the environment page; url links the version |
at | no | ISO time or Unix seconds; used only if within a day of now |
The answer lists the keys recorded, the keys ignored (their space doesn't exist on the site, so
"UTF-8" in a commit message is not a work item), and what happened with Jira's Deployments panel.
GET with the token answers which environments the token may report to (a quick test).
How deployments change what Berth shows:
- successful: the version becomes the environment's current version, and every work item key in it is "on" the environment from this version.
- in_progress / pending: the board shows "deploying" (for up to 2 hours).
- failed: the board flags "last deploy failed"; the current version stays.
- rolled_back: the work item keys you send are taken off the environment.
What is on an environment
Click an environment on the board. Work items on it lists the work items it holds (only ones you can see), with their status and the version they arrived in. Not yet on compares it with another environment, for example everything on staging that isn't on production yet.
The work item panel
Open any work item and the Environments (Berth) panel shows which environments have it and since which version, the production environments that don't have it yet, bookings made for it, and what each environment runs now.
Statuses
| Status | Meaning |
|---|---|
| free | Bookable and nobody has it |
| booked | Someone has it now |
| deploying | A pipeline reported in_progress or pending in the last 2 hours |
| maintenance / down | Set by the owner or a Jira admin, with a note. Down environments can't be booked |
| not bookable | Production and other environments nobody books |
Dashboard widget
Add Environment status (Berth) to a dashboard and pick a group and tiers.
Moving from Data Center
If you used an environment app on Data Center, add the same environments in Berth with the keys your pipelines already send, create one token per pipeline, and point the pipelines' deployment step at Berth's endpoint. Bookings start fresh; the board shows current versions after each pipeline's next run.