Skip to content

Protect production deploys with DueReason

Make a deploy pipeline itself refuse without an approved grant: a required GitHub status check, a pipeline verify step, and duereason-gate for other CI.

Updated · 8 min read

In short

  • A local gate runs on whoever's machine files the request; anyone with shell access on that machine can skip it. The system that actually merges or deploys has to refuse on its own, without a grant to check.
  • duereason/approve's verify mode, given no grant input, looks up the newest APPROVED request for the exact action and payload and checks its grant offline -- the same check a required GitHub status check or an independent deploy step can run even though neither ever received a grant output from anywhere.
  • Three places to put it: a required status check on pull requests, a verify step at the top of the deploy job itself, and duereason-gate verify for a CI system that is not GitHub Actions.
  • request-if-missing turns a missing approval into a clear, re-runnable failure instead of a silent pass: file the request and fail, so the same check turns green the moment it is approved.

A gate that only runs where an agent or a developer happens to be executing is a gate anyone with shell access on that machine can skip: comment it out, run the deploy script directly, merge with --admin. Protecting production means the system that performs the protected action -- GitHub merging a pull request, a pipeline running a deploy -- refuses on its own when nothing approved exactly this. That is a second, independent check at the target, not a replacement for the one closer to the agent.

What the lookup checks

duereason/approve's verify mode normally checks a grant you already hold, offline, against a payload: the same signature, expiry, organization and payload-hash checks described in the grant-verification guide. Leave grant empty and it does something new: it asks DueReason for the newest request with status=approved for this exact action and payload hash (the API's GET /approvals endpoint now accepts a payloadHash filter for this), takes the grant that request carries, and verifies that offline exactly the same way. Nothing before the HTTP call has to be trusted: the lookup is scoped to your organization's API key, and the offline check afterward refuses a grant for another organization, another action, an edited payload or one that has since expired, whether or not the lookup is itself attacked.

This is what makes verify usable somewhere that was never handed a grant output in the first place -- a required status check running in its own job, a deploy pipeline whose only input is the commit it was triggered on.

1. A required status check on the deploy repository

Add a workflow that runs on pull_request, pull_request_review (so a later approval re-triggers it) and workflow_dispatch (so it can be re-run by hand once approved), with a job that runs duereason/approve in verify mode against a payload built from the PR: repository, PR number, head SHA and target environment. Name the job something stable (duereason-verify, say) and add exactly that name as a required status check in the repository's branch protection settings for the protected branch, with Include administrators turned on -- the point is that nobody, including an owner, merges around it by accident. A ready-to-copy version of this workflow lives in the Action's own README inside the cra-platform monorepo, next to the verify-mode usage example -- uses: duereason/approve@v1 is not yet resolvable as a GitHub Actions reference until that Action repository is public (unlike @duereason/gate, already on npm). If you are already relying on GitHub Environments' required reviewers for this, the guide comparing GitHub's built-in review to an approval gate covers exactly where that stops and what this status check adds on top.

2. A verify step at the top of the deploy job

Even with the status check above, the job that actually runs the deploy should check again right before it executes: a branch protection rule only stops a merge, not a later re-run of an already-merged workflow, a manually triggered deploy, or a rollback to an older commit. Put a verify step as literally the first step of the deploy job, with the same payload shape (repository, commit SHA, target environment) the status check used; if DueReason's answer and the branch protection check ever disagreed, this step is the one that actually has the authority to stop the deploy.

3. Non-GitHub CI: duereason-gate verify

GitLab CI, Jenkins, or an Argo CD pre-sync hook never ran duereason/approve in the first place, so there is no grant output to carry forward. @duereason/gate's CLI (duereason-gate) ships a verify subcommand for exactly this: npm install -g @duereason/gate installs it, the same command Settings > Agent gate shows per harness, and duereason-gate verify --action production-deploy --payload '{"repo":"acme/shop","sha":"abc123","environment":"production"}' reads DUEREASON_API_KEY, DUEREASON_ORG and (self-hosted only) DUEREASON_URL from the environment or ~/.config/duereason/credentials, runs the identical lookup-and-verify-offline check, prints the matched request id on success, and exits 2 with a reason otherwise -- a plain process exit code any CI system can gate a stage on. It never files a request: check and exec are the commands that file one and wait.

When nothing is approved yet: request-if-missing

A status check that just fails silently the first time a PR is opened is confusing: did it fail because something is wrong, or because nobody has approved it yet? Set request-if-missing: "true" on the verify step and, when the lookup finds nothing, it files the same request mode: request would (using the reason input) and still fails the job -- but now with a link to the request it just filed. Re-running the check (the pull_request_review trigger above does this for you on every review) passes the moment that request is approved, with no separate request step to keep in sync.

The DueReason side: a workflow with more than one step

None of this matters if the workflow behind the action approves itself. Configure the production-deploy action in DueReason with a workflow that actually makes someone decide: a first step naming the release owner and requiring a written reason, a second step requiring two members of an Ops group. The grant this produces only exists once every step is answered, and verify's lookup only ever matches a request whose status is approved -- a request still waiting on its second step is invisible to it, exactly like a rejected or expired one.

Questions

Does the required status check need the grant output from somewhere else in the workflow?
No. That is the point of the lookup: leave the verify step's grant input empty and it asks DueReason for the newest approved request matching the exact action and payload hash instead of trusting a value handed to it by another job.
What stops someone from approving their own deploy?
The workflow configured for the action, same as any other DueReason approval: name the groups and the number of distinct approvers a step needs, and a requester who is not in an eligible group (or who already answered an earlier step) cannot also answer a later one.
Can request-if-missing be used to skip review entirely?
No: it only files the same request a normal mode: request step would and still fails the job immediately. Nothing merges or deploys until a person actually approves that request through the workflow configured for the action.
Does this replace the local gate (duereason-gate check / exec)?
No, it complements it. The local gate stops an agent from even attempting the action; the target-side verify stops the action itself from succeeding if the local gate was bypassed, misconfigured, or simply never installed on whatever is running the deploy.
What if the status check and the deploy's own verify step disagree?
They should not, since both ask the same API the same question, but the deploy's own verify step is the one with real authority: a branch protection rule only ever stops a merge, never a later re-run, a manual trigger, or a rollback to an older approved or unapproved commit.

Read the full grant and API reference

The payloadHash filter on GET /approvals, the verify-mode inputs and outputs, and every grant claim an executor can check live in the API reference.

Read the API docs

Sources

This guide explains the regulation as we read it; it is not legal advice. Check the official text and your national law, which may add obligations.

Start with DueReason

Create a free account, try it live, or talk to us about your workflow.

Get product updates