Releases and automatic moves

An issue can move by itself: to review when its merge request is opened, to «on staging» when a pipeline puts it there, to closed when the release it went out in ships. Nobody has to remember to drag the card, and the board says where the work really is.

• A workflow with a state for each step — the ready-made «Releases by environment», or your own.
• Rules: an event, the state the issue must be in, and the state it moves to.
• The repository’s webhook, so the tracker hears of a branch and a merge request when they happen.
• One request from your pipeline saying what went out, and where.
• Versions — the releases an issue goes out in.

Each part works without the others. Everything on this page is set up by the project’s lead, from the board’s ⋯ menu.

1. Open the board, then ⋯ → States & transitions…
2. Press Use another… and choose Releases by environment.
3. If the project already has issues, say for each state they stand in which new state they go to.
4. Press Use Releases by environment.

Closed and Cancelled can be reached from every unfinished state, so work that goes out to no environment — a chore, an investigation — is closed from where it stands. The moves have names of their own («Deploy to Staging», «Preprod verified»), and a tool reads those names in transitions[].name.

With the workflow come three environments — dev, staging, prod — where the project had none, a board column per state where the board had no columns of its own, and seven rules, switched off. The workflow becomes the project’s own: edit it afterwards like any other.

The rules come switched off on purpose. Until you switch one on, nothing moves by itself — see the next section.

⋯ → Rules… lists the project’s rules. The seven that come with the workflow:

Switch on the ones your project has the plumbing for. You can also write your own: any of these events, plus «all its sub-tasks are finished» and «the issue entered a state»; a merge-request rule can be narrowed to the branch it is merged into, a deployment rule to one environment.

• A rule moves an issue as whoever switched it on. The issue’s history says «the rule “…” (for Anna)». If that person leaves the project, the rule switches itself off rather than run on nobody’s access.
• It is an ordinary move. The workflow’s conditions apply. If the workflow does not allow the move, nothing happens to the issue, and the rule’s journal says why.
• «From» is checked every time. An issue that is not in the state the rule names is left alone — a merge request opened on an issue already in testing does not drag it back.
• Every pass counts. An issue sent back and brought round again is moved by the same rules the second time.
• A rule’s move can fire the next rule, three moves deep at most.

The three moves between them stay with a person, because each is a judgement: «I am testing it», «it passed», «staging is fine».

The repository has to be connected first: ⋯ → Repositories… (GitLab or GitHub).

1. In Repositories…, press Set up webhook on the repository.
2. Press Generate and copy the Address and the Secret — the secret is stored sealed and never shown again.
3. In GitLab: Settings → Webhooks → Add new webhook. Paste the address as the URL and the secret as the Secret token; tick Push events and Merge request events.
4. In GitHub: Settings → Webhooks → Add webhook. Paste the address as the Payload URL, choose application/json, paste the secret, and select Pushes and Pull requests.
5. Save in both places. The sheet then says when the host was last heard and what it said — a test delivery counts.

An issue is named by its key — ABC-12 — in the branch name, the merge request’s title or its description. Only issues of the project the repository is connected to are moved.

• The same delivery sent twice — a retry, «Resend» — moves an issue once.
• Everything else the host sends (an update, an approval, a tag) is heard and ignored.
• The host’s delivery log shows our answer: 200 with outcome — taken, duplicate, ignored, wrongRepository, disabled — or 401 when the secret is not this repository’s.

Without a secret a repository accepts nothing. GitHub’s form-encoded content type is refused: choose application/json.

⋯ → Environments… keeps the project’s environments in order — the last one is where finished work ends up — and shows the command below with your project’s address in it. A step in the pipeline runs it after the deployment has succeeded:

deploy_staging:
  stage: deploy
  script:
    - ./deploy.sh staging
    - |
      curl -fsS -X POST "https://<workspace>.kaiku.tech/api/projects/ABC/deployments" \
        -H "Authorization: Bearer $PM_TOKEN" -H "Content-Type: application/json" \
        -d "{\"environment\":\"staging\",\"id\":\"$CI_PIPELINE_ID\",\"revision\":\"$CI_COMMIT_SHA\",\"url\":\"$CI_PIPELINE_URL\",\"fromLast\":true}"

PM_TOKEN is a masked CI/CD variable holding a token of somebody who may change issues in the project — see Connecting a tool. The example is GitLab CI; any pipeline that can send a request will do.

• Told once. The same id for the same environment again answers repeated: true and does nothing, so a retried step is safe.
• The answer lists issues it carried, unknown keys that are no issue of the project, how many times a rule ran (rulesRan), the from a range was read from, and — on the last environment — unfinished: the issues that went out and are not in a finished state.
• A range needs the repository connected, and reads commit messages: a merge commit names its branch, a squashed one carries the request’s title. If the repository does not answer, the request fails with 502 and nothing is recorded — run the step again.
• With fromLast, the first report to an environment reads no range: there is nothing before it. It records where the next one starts.
• An environment or a version the project does not have is refused with a 400 — never quietly skipped.

Prefer fromLast to your CI’s «previous commit» variable. That variable is the last deployed commit only if every pipeline deploys; one cancelled or failed pipeline, and its issues are never told they went out.

• The issue shows Lies on with every environment it has reached; each opens the pipeline that put it there. An issue on prod still says staging too.
• Its history gets one line per environment — «deployed to staging» — however many times it is deployed there.
• The board has a Lies on filter.
• An issue on the last environment that is not finished says so on its Lies on row for as long as that is true.
• Over the API the field is deployedTo, beside the standard ones; in a search it is returned when asked for by name.

⋯ → Releases… lists the project’s versions with their dates and progress. An issue may be in several — one per staging cut is a common way to use them — and the issue’s Release row sets them.

• Release marks a version released. If it still holds unfinished work, the screen asks first: leave it, or move it to a version that is still ahead.
• Releasing fires the «version released» rule for each issue still in the version. An issue taken out of a release it missed is not moved.
• In a search: fixVersion = "2.4.0", fixVersion in releasedVersions(), fixVersion in unreleasedVersions().
• Over the API a version is the standard /rest/api/2/version resource, and an issue’s are its fixVersions; an issue takes versions of its own project only.
• A pipeline can put issues in a version as it deploys them: the version field above.

A webhook you register hears versions too: jira:version_created, jira:version_updated, jira:version_released, jira:version_unreleased, jira:version_deleted.

• A rule cannot change the assignee — only move an issue, add a checklist, or hand the issue to an agent.
• A reported deployment cannot be taken back. A wrong report is corrected by the next one to that environment.
• There is no search clause for «lies on»; the board filters its cards.
• A webhook you register is not told about deployments.
• The ready-made workflow is taken on the screen; there is no MCP tool for a project’s workflow.
• A project mirrored from another tracker takes no deployment reports: its issues live there.