Change management

Production is a GitOps branch. The deployed version is defined by the contents of version.txt on the production branch, which holds the git SHA to release. A change to production is a release.

This page describes how releases are proposed, reviewed, and deployed. Releases are on-demand: an engineer cuts a release when there is something to ship. The change management record for any release is the pull request that modifies version.txt.

Pre-conditions

By the time a SHA is a candidate for release, it has already been merged to main, deployed to beta, and exercised by the post-merge test suite (see Shipping code). The release process governs the promotion from beta to production, not the original change.

Creating a release PR

The simplest path is mise run release, which opens a release PR against production from the template with the candidate SHA filled in. Manual creation is also fine.

When the PR opens, three things happen automatically:

• A GitHub Action generates the changelog from the diff between the previous and proposed SHA. This is plain code, not AI.
• The same action normalises the PR summary and description into the expected format, in case the author missed a field.
• A Claude Code bot attaches an asynchronous comment with a suggested risk rating, specific items to watch for in the release (e.g. database migrations), and links to the policies and procedures that apply to those items.

The Claude Code bot is decision support for the reviewer, not a substitute for them. If it fails, is incorrect, or contradicts itself, the reviewer’s own assessment stands.

Branch protection on production

Direct pushes to production are blocked. A PR is mergeable when:

• The author and the approving reviewer are different people.
• The proposed SHA is a valid commit in the repository.
• A risk: low, risk: medium, or risk: high label is applied.
• All required CI checks pass.

The reviewer’s job

A reviewer reads the changelog and the bot’s comment, then completes the PR template checklist:

• I have reviewed the changes in this release.
• I have applied the appropriate risk label.

If the risk label is high, two more items are required:

• I have reviewed the rollback procedure and confirmed it is applicable to this release.
• Post-deploy monitoring has been scheduled per the incident response policy.

The reviewer then approves or denies the PR.

Risk levels

Releases are labelled risk: low, risk: medium, or risk: high. The reviewer chooses the level based on the contents of the release. There is no fixed criterion: it is a judgement call informed by the changelog, the bot’s assessment, and the reviewer’s knowledge of the affected components.

A risk: high release requires:

• Notes on rollout and rollback in the PR description.
• A scheduled post-deploy monitoring period.

risk: low and risk: medium releases have no additional requirements beyond the standard checklist.

Deployment

When the PR merges, the deployment runs automatically. A comment on the release PR links to the deploy run and is updated with the final status when it completes. The comment is the visible record of deploy outcome.

Smoke tests run automatically against production after a deploy completes. Alarms for elevated error rates and other production health signals fire in incident.io independently of the deploy itself.

Recovery

A failed deployment, or a successful deploy that turns out to have shipped a problem, is the responsibility of the person who initiated the release. The investigation runs under Incident response.

The recovery path depends on what was changed:

• Reversible changes (no schema migrations, no data deletion, no irrevocable side effects). Open a new release PR that sets version.txt back to the previous SHA. It goes through the standard process and deploys the previous version.
• Destructive changes (schema migrations, data deletion, any irrevocable side effect). Roll forward only. Apply a fix on main, take it through the SDLC and beta, and release it through the standard process.

Changineers does not maintain a hotfix path that bypasses the release PR. The aim is to keep the standard process fast enough that a hotfix isn’t worth the risk of an unreviewed change.

Authorised actors

Production deployment runs in GitHub Actions using OIDC-federated IAM roles. There are no long-lived AWS access keys held by humans or in any system.

The release PR is the only standard path to changing production. Engineers who need elevated AWS access for an exceptional case (direct CLI or terraform apply) request elevated privileges. The CTO is the sole approver; on approval they grant access by increasing the engineer’s AWS SSO permissions for the duration of the work.