Jira

How work is tracked, from an idea to a change running in production.

Jira is the one place a piece of work lives: its description, discussion, approval, status, and the code that implements it. There is no separate ticket page and no GitLab issue any more. Branches, commits and merge requests carry the Jira key, and GitLab's Jira integration links them to the ticket.

This document is the work-tracking side of the delivery model. How a change gets onto main is branching.md; how main reaches production is release.md; what "finished" means at each level is definition-of-done.md.

Why

A look at the backend projects (AST, AGM, DP, AP, AS) on 2026-10-06 found:

Concern	What the projects did
Workflow	Jira's default `To Do -> In Progress -> In Review -> Done` everywhere
Project style	AST and AP company-managed; AGM, DP and AS team-managed, so no shared configuration was possible
Issue types	A different set per project: Feature and Story both in use, Incident only in DP

The default workflow ends at "Done" when the merge request merges. Since the CI/CD standard, a merge only reaches staging; the work is verified on a build there, and production gets it on the next release day. So "Done" in Jira said nothing about whether users had the change. This workflow gives each of those steps a status.

Hierarchy

Level	Issue type	Created by	What it is
Epic	Epic	BA or PM	A goal that takes weeks: "Invoice export", "Cut p95 below 300ms"
Work item	Story, Bug, Task	Story: BA. Bug and Task: anyone	One outcome that can be verified on staging and shipped by a release
Engineering unit	Subtask	The BE or FE engineer doing it	One engineer's piece of a work item, usually one merge request, at most 3 days

Story is a user-visible change. The BA writes it, and during refinement turns it into a detailed spec with acceptance criteria and test scenarios.
Bug is behaviour that differs from what was specified or what users rely on.
Task is engineering work with no user-visible change: tech debt, infra, a spike, docs, an incident record (label incident), an incident follow-up (label incident-followup).
Subtask is where engineers plan and track their own work. A Story usually has a BE subtask and an FE subtask; bigger ones have several of each.

There is one type per purpose. Feature is retired in favour of Story, and Incident in favour of a Task labelled incident. An incident is coordinated in Slack; its Task holds the write-up and postmortem, and its follow-ups are Tasks labelled incident-followup, linked to it (Incidents & Postmortems).

A work item is sized so it can be verified and shipped on its own: at most two weeks of the team's work. Bigger work is split into several work items under the Epic.

Who verifies

The team has no QA engineer for now. Until it does, testing is the developers' job and acceptance is the BA's:

Who	Does	When
The developer (subtask author)	Writes an automated test for every `auto` test scenario, in the MR that implements it	Level 1, before merge
The MR reviewer	Checks that each `auto` scenario the MR claims has a test, and that the test really checks the scenario	Level 1, in review
The developer (work item owner)	Runs the `manual` scenarios on the staging build and posts the results	In Verification
The BA	Checks the feature on staging against their own spec, and accepts or rejects it	In Verification

The work item owner is the developer of its main subtask; with several, the lead names one at refinement. The full testing process is in Testing.

Work item workflow

Applies to Story, Bug and Task.

Backlog -> Refinement -> Ready -> In Progress -> In Verification -> Ready for Release -> Done
              any status -> Closed (with a reason)
              In Verification -> In Progress (a scenario failed)

Status	Means	Moves here when	Moved by
Backlog	Filed, not yet looked at in detail	Created	Anyone
Refinement	A developer is researching it and the BA is writing the detailed spec	Picked at grooming, with a developer assigned	Lead
Ready	Meets the Definition of Ready; work can start	The refinement review passes	Lead or BA
In Progress	Developers are working on its subtasks	The first subtask moves to In Progress	Automation
In Verification	Every subtask is merged, so the work is on staging, waiting for the developer's and the BA's checks	The last subtask moves to Done	Automation
Ready for Release	Verified by the developer and accepted by the BA on a named staging build	The BA accepts	BA
Done	Live in production	Its Fix Version is released	Automation
Closed	Not done: duplicate, won't do, out of scope, or stale	Decided at any point, with a one-line reason	Lead, BA or reporter

Rules

Developers pull from Ready, never from Backlog or Refinement. Starting before the spec is clear is how scope grows mid-flight.
Verify a build, not a branch. Both sign-off comments name the staging build version, #{pipeline_id}-{short_commit_ref}.
A failed scenario goes back to In Progress with a new subtask fix: <what failed>, assigned to whoever owns that part. The history stays on one ticket.
Fix Version is set when the BA accepts: the next vX.Y.Z of that repository. One Jira version per release tag.
Done means users have it. Approved, merged or verified on staging are all earlier statuses.

Developers don't wait for a finished spec; they help produce it. The goal is that, before any code is written, everyone agrees on exactly how the feature should behave, including the error cases, so the test scenarios can be written down and checked later.

Grooming picks the work item and assigns a developer, normally the one who will build it. The work item moves to Refinement. Timebox: two working days.
The developer researches, for an hour or two, not days:
- the code paths and data the change touches, and similar features that already exist;
- edge cases: empty data, limits, concurrent requests, permissions, retries, large volumes;
- dependencies and risks: other services, migrations, backward compatibility, performance;
- anything the description leaves open.
The developer posts the findings and questions as one comment on the work item, mentioning the BA. Questions are specific and answerable: "What happens when the user has no events: an empty list or a 404?", not "please clarify".
The BA answers by extending the description into the detailed spec, not by replying in comments, so the description stays the single place to read the requirement.
Refinement review, 15 minutes: developer, BA and lead read the spec together. The developer creates and estimates the subtasks, tags each test scenario auto or manual, and the lead confirms the estimates. If every Definition of Ready item holds, the work item moves to Ready.

If the open questions can't be answered in the timebox, the work item goes back to Backlog with what was learned, or the unknown becomes a spike Task.

The detailed spec

For a backend team the detailed picture is short text in the Jira description, using this template. It describes behaviour, not implementation: endpoints are listed with a note, not specified field by field.

Goal
  One or two sentences: who needs what, and why.

Flow (optional)
  1. The happy path, step by step, from the caller's point of view.
  2. ...
  What can go wrong: one line per failure and what the caller gets.

Endpoints
  GET  /v1/users/{id}/activity  List a user's events, newest first.
                                Paging offset/limit (max 100). No filters.
                                Returns event type, time and metadata.
  POST /v1/...                  ...

Rules
  - Business rules and edge cases, one per line.
  - Without a Flow: the failure cases go here too, with what the caller gets.

Acceptance criteria (Given / When / Then)
  AC1. Given ..., when ..., then ...

Test scenarios
  | ID | Scenario | auto / manual | Test name (filled in by the developer) |
  | S1 | ...      | auto          | TestActivity_S1_OwnEvents              |

Notes
  Dependencies, data touched, out of scope. Leave out what doesn't apply.

Open questions
  Must be empty before Ready.

Flow is optional. Write it when the feature is a sequence of steps across calls or services (a checkout, a sign-up, a background job pipeline). Skip it when the work is one or a few independent endpoints or an internal change: the Endpoints and Rules already say what happens, and the failure cases move into Rules.

Request and response bodies are not written here. The developer defines them in the code and the Swagger/OpenAPI spec, which the MR updates.

An example is in Jira work item examples.

Definition of Ready

A work item moves to Ready only when all of these are true:

The description follows the detailed spec template: goal, the endpoints (if any) with a note each, rules, and a flow when the feature spans several steps. Every failure case is written down, in the flow or in the rules.
Acceptance criteria are written as Given / When / Then.
Test scenarios cover every acceptance criterion, including the failure cases, and each is tagged auto or manual.
Open questions is empty: the developer's research questions are answered in the description.
Dependencies in Notes are confirmed available.
Epic link (Stories) and component set; the work item owner is named.
Subtasks created and estimated by the developers who will do them, and the lead has confirmed the estimates.

Testing

Three layers, from cheapest to most expensive. The more scenarios are automated, the less the manual checks have to cover.

1. Automated scenario tests, in every MR

Default to auto. A scenario is manual only when automating it costs more than it is worth: visual checks, third-party sandboxes, or one-off data. Most backend scenarios can be automated.
The test lands in the same MR as the code it covers. A subtask is not Done with its tests "to follow".
Name the test after the scenario (TestActivity_S3_NoEventsReturnsEmptyList), and fill the test name into the spec's scenario table, so anyone can trace a requirement to its test.
Test through the real boundary: call the HTTP handler or the service against a real Postgres (testcontainers), not mocks of our own code. The test should fail if the feature broke the way a user would notice.
CI runs them in the blocking test job, so a broken scenario cannot merge.
The MR's Test Notes list the scenario IDs the MR automates. The reviewer checks each one.

2. Developer verification on staging

When the work item reaches In Verification, its owner runs every manual scenario on staging, plus a quick pass over the happy path, and posts:

Verified on staging build #486-b2c3d4e
S1 auto  pass (CI)
S4 manual pass: <what you saw>
S5 manual pass

3. BA acceptance on staging

The BA checks the feature on the same staging build against the spec they wrote: does it do what the business asked, and do the failure cases read sensibly? They then post "Accepted on build #486-b2c3d4e", set the Fix Version and move the work item to Ready for Release; or describe what is wrong and move it back to In Progress.

Not built yet

A staging smoke suite (make test-smoke) that runs after every deploy:staging would catch environment-only breakage automatically. release.md already expects one for compat:check; until a repository has it, layer 2 covers that gap by hand.

Parked work

A feature can be finished before the business has decided to ship it (branching.md). Its work item stays In Progress, flagged (Jira's flag), with the label parked and a due date no more than 30 days out. Its subtasks stay In Review with draft merge requests. On the due date it either merges behind an off flag and continues, or it is Closed and the branch deleted.

Hotfixes

A production fix that cannot wait is a Bug with priority Highest. It follows the same workflow, with the Fix Version set to a patch release outside the Monday/Wednesday cadence (release.md).

Subtask workflow

To Do -> In Progress -> In Review -> Done

Status	Means	Moved by
To Do	Planned, estimated	The engineer
In Progress	Being worked on. Counts against the WIP limit	The engineer
In Review	Its merge request is open	The engineer
Done	Merged to `main`, which deploys it to staging	GitLab, when the merge request merges

WIP limit: one or two subtasks In Progress per engineer.
One assignee per subtask. A subtask two people share is two subtasks.
A subtask is Done when its merge request merges; the subtask Definition of Done lists what has to be true by then.
Work an engineer finds mid-flight (a refactor, a missing index) becomes a new subtask, or a Task if it doesn't belong to this work item.

Fields

Keep the field set small; every required field is a reason not to file a ticket.

Field	Required on	Values
Priority	Work items	`Highest` (drop everything), `High` (this iteration), `Medium` (next), `Low` (someday)
Component	Work items	The domain: `auth`, `billing`, `ingestion`, ... Its default assignee is the domain owner
Labels	Optional	`tech-debt`, `infra`, `spike`, `docs`, `incident`, `incident-followup`, `parked`
Fix Version	Work items, set when the BA accepts	`vX.Y.Z`, matching the git tag
Original estimate	Subtasks	Hours or days
Epic link / parent	Stories, subtasks	The Epic; the work item

Priority replaces the playbook's earlier P0 to P3 labels: Highest = P0, High = P1, Medium = P2, Low = P3.

GitLab and Jira

Everything below hangs off the subtask key (AST-142). The work item gets the links through its subtasks.

Where	Convention	Example
Branch	`<type>/<KEY>-<short-description>`	`feat/AST-142-invoice-export`
Merge request title	`<KEY> <conventional commit subject>`	`AST-142 feat(usage): add invoice export`
Merge request description	Ends with `Closes <KEY>`	`Closes AST-142`
Squash commit	Conventional Commit, key in a footer	`feat(usage): add invoice export` ... `Refs: AST-142`
Release	One Jira version per tag, same name	Tag `v1.4.0`, Jira version `v1.4.0`

With the key in the branch name, Jira's development panel shows the branch, commits, merge request and pipeline on the subtask. Closes AST-142 makes GitLab move that subtask to Done when the merge request merges into main.

The key goes in the subtask, not the work item, because a work item usually spans a BE and an FE merge request. A merge request that genuinely covers a whole work item with no subtasks (a one-line Bug fix) uses the work item's key and the same conventions.

Automation

Three Jira Automation rules carry the work item through its statuses, so nobody has to remember to. Each is scoped to the backend projects.

#	When	If	Then
1	A subtask moves to In Progress	Its parent is in Ready	Move the parent to In Progress
2	A subtask moves to Done	Every subtask of the parent is Done or Closed	Move the parent to In Verification, and comment "All subtasks merged. Owner: verify the manual scenarios on staging. BA: accept on the same build."
3	A version is released	-	Move every work item in that version from Ready for Release to Done

Rule 3 is the last step of every release: releasing the Jira version once the deploy is healthy (release.md).

Setting it up

For the Jira admin. Do this once, in this order.

One workflow scheme, two workflows. The work item workflow includes the Refinement and In Verification statuses. Create the work-item workflow and the subtask workflow above as company-managed workflows, and one scheme that maps Story, Bug and Task to the first and Subtask to the second.
One issue type scheme: Epic, Story, Bug, Task, Subtask.
Move the team-managed projects to company-managed. AGM, DP and AS are team-managed, so they cannot share a scheme. Create a company-managed project for each, then bulk-move the issues, mapping Feature to Story, Incident to Task with label incident, and each old status to its new one: To Do to Backlog, In Progress to In Progress, In Review to In Progress, Done to Done.
Apply both schemes to AST, AGM, DP, AP and AS.
Components per domain, with the domain owner as default assignee.
The three automation rules above.
GitLab's Jira integration on each repository (Settings, Integrations, Jira): enable "Enable Jira transitions", and set it to the transition ID of the subtask's In Review -> Done transition. Turn on the Jira development panel through the GitLab for Jira Cloud app.
Versions: from the next release on, the releaser creates vX.Y.Z in the repository's Jira project when the BA accepts the first work item for it.

Until step 3 is done, a team-managed project keeps the same status names by hand, so the workflow reads the same everywhere even before it is enforced.

Last updated: 2026-10-06. Found something wrong? Open a PR.

Jira ​

Why ​

Hierarchy ​

Who verifies ​

Work item workflow ​

Rules ​

Refinement ​

The detailed spec ​

Definition of Ready ​

Testing ​

1. Automated scenario tests, in every MR ​

2. Developer verification on staging ​

3. BA acceptance on staging ​

Not built yet ​

Parked work ​

Hotfixes ​

Subtask workflow ​

Fields ​

GitLab and Jira ​

Automation ​

Setting it up ​