Jira Release Reporting

Provision the credential that lets a release tell Jira what shipped, and run the one-time cutover that put every deploy job back on a single Environment per tier.

Owner: PlatformWhen to use: credential setup, rotation, or the one-time cutover

Canonical sources. .github/scripts/report-jira-deployment.ts is the reporter, .github/scripts/jira-environment.ts declares each environment's Jira type and the site's cloud id, and .github/actions/record-deployment/action.yml is what calls them. This runbook is the HOWTO for the parts that live outside the repo.

TL;DR

🅰 Why

Jira used to guess. Its GitHub integration read Deployment records as a release timeline, so a phantom record from a cancelled run silently dropped issues from the next release's window.

🅱 Now

The release states its own contents. Version, environment type and issue keys are POSTed to Jira explicitly, so no window is inferred and no record can move one.

🅲 Cost of skipping

Nothing breaks. With no credential the reporting step warns and exits 0. Deploys are unaffected; only the Jira release panel goes unpopulated.

Cutover order — and why it is not negotiable

The trust-policy change NARROWS what each deploy role admits, from two OIDC subjects per tier down to one. Applying it before the workflow bindings are live leaves every deploy job presenting a subject the policy no longer trusts, which fails closed on AssumeRoleWithWebIdentity — the same break this whole change came out of, in the opposite direction.

1

Merge

GitHub

2

Apply ci-identity

admin + Pulumi

3

Delete the parallel envs

GitHub settings

4

Jira credential

Jira site admin

5

Repo secrets

gh CLI

6

Verify

next release

Merge the PR first. This puts the workflow bindings back on the bare <env> Environment, which every deploy role already trusts. Nothing breaks at this point because the trust policy still admits both subjects — the old parallel one is simply unused from here on.

Then narrow the trust policy. Only now, with nothing binding the parallel subject:

cd infra/ci-identity && AWS_PROFILE=admin PULUMI_BACKEND_URL=s3://onramp-pulumi-state-111776553558 pulumi preview --stack identity-tier --non-interactive

Expect ~assumeRolePolicy on 8 roles and nothing else. ci-identity owns the deploy roles, the migrate-starter roles and the permissions boundary across all five tiers, and it does not converge from any workflow — so anything else that landed in infra/ci-identity since the last apply goes out in the same up. Read the diff before proceeding.

cd infra/ci-identity && AWS_PROFILE=admin PULUMI_BACKEND_URL=s3://onramp-pulumi-state-111776553558 pulumi up --stack identity-tier

Delete the five parallel Environments — ci-dev, ci-stage, ci-prod, ci-demo, ci-gdpr-prod — under Settings → Environments in the repo, or:

for e in ci-dev ci-stage ci-prod ci-demo ci-gdpr-prod; do gh api -X DELETE "repos/OnRampTech/main-web-application/environments/$e"; done

Do this AFTER step 2, not before. Deleting an Environment a live job still binds makes GitHub auto-recreate it blank on the next run — no branch/tag allow-list, no DUPLO_TENANT_NAME — which is an availability break for the agent deploys and a silent ref-policy hole for the rest.

A Jira site admin creates one OAuth credential. It is a system-to-system credential, deliberately not tied to any Jira user, so it survives people joining and leaving. Full detail in the next section.

Store the pair as repository secrets. Run these and paste the value at the prompt — do not pass secrets as command arguments, where they land in shell history:

gh secret set JIRA_CLIENT_ID --repo OnRampTech/main-web-application

gh secret set JIRA_CLIENT_SECRET --repo OnRampTech/main-web-application

Repository-level, not environment-level: record-deployment runs on every tier's rollout leg and the credential is the same for all of them. This matches how DUPLO_TOKEN is already stored.

The next release is the proof. In the Record deployment step's log, expect:

Reporting v4.36.0 → prod: 14 issue key(s) over a1b2c3d4..e5f6a7b8
Jira accepted the prod deployment for ONRAMP-1234, ONRAMP-1235, ...

Then open one of those issues and confirm the Releases panel shows the environment. A ::warning line instead means reporting was skipped or rejected — see Troubleshooting. Either way the release itself is unaffected.

Instructions for the Jira site admin

Hand this section over verbatim. It needs Jira site admin, takes about two minutes, and grants nothing beyond writing DevOps metadata.

What this is. A system-to-system OAuth credential that lets our GitHub Actions release pipeline post deployment records to Jira. It is not associated with any Jira user account, cannot read or modify issues, and continues working regardless of user changes.

1. In Jira Cloud, select the gear icon (Settings).
2. Choose Marketplace apps.
3. In the left sidebar, select OAuth credentials.
4. Select Create credentials.
5. Fill the form:
   • App name — OnRamp GitHub Actions release reporting
   • Data Center base URL — https://github.com/OnRampTech/main-web-application
   • Logo URL — optional; leave blank or use any GitHub icon URL.
   • Permissions — grant Deployments only. Do not grant Builds, Development information, or Feature flags; the pipeline does not call those APIs and the credential should not be able to.
6. Select Create.
7. Copy the client ID and client secret and send them to the requester through a secret-sharing channel — not Slack, not email.

Permissions can be changed later from the credential's ⋯ Actions menu → Edit permissions, so an over-broad grant is fixable without recreating it.

Treat the secret as show-once. Atlassian's docs do not state whether the client secret can be re-read after creation, so assume it cannot. If it is lost, delete the credential and create a new one rather than hunting for it.

Rotation

The credential has no expiry, so rotation is only for suspected exposure or routine hygiene. It is a straight replace with no coordination needed:

1. Admin creates a NEW credential per the steps above.
2. Update both repository secrets to the new pair.
3. Admin deletes the old credential.

Order matters only in that step 3 comes last. Reporting is best-effort, so even a window where both are briefly wrong costs warnings in a deploy log and nothing else.

Troubleshooting

Log line	Cause	Fix
JIRA_CLIENT_ID / JIRA_CLIENT_SECRET not set — skipping	Secrets absent	Steps 4–5 above
Jira token request failed: HTTP 401	Wrong or revoked credential	Rotate; confirm both secrets came from the same credential
Jira accepted 0, rejected 1	Payload refused	Read the quoted message — usually an empty issueKeys, which the script already guards
unknown issue keys: ONRAMP-…	Key in a commit message does not exist in Jira	Usually a typo in a commit; harmless, the rest still associate
no Jira environment type declared for "X"	A new environment reached record-deployment	Add it to JIRA_ENVIRONMENT_TYPE in .github/scripts/jira-environment.ts
No ONRAMP issue keys in this release's commit range	Genuinely no keys, or a shallow clone	The action deepens history itself; if it persists, the range really is keyless
Could not find <env>'s previous release in N deployment records	The previous rollout record is further back than MAX_HISTORY_PAGES pages of deployment history	Deliberate: reporting nothing beats reporting a window that would be wrong. Usually means an unusual burst of out-of-band deploys — raise MAX_HISTORY_PAGES in report-jira-deployment.ts if it recurs

Never make the reporting step fail a release. Every failure path in report-jira-deployment.ts warns and exits 0 on purpose. A release that shipped must not be reported as failed because a metadata call did not land.