RFC: Two scoped GitHub Apps for unattended dmf-cms releases

[znerol2]

Decision requested

Should dmfdeploy introduce two narrowly scoped GitHub Apps so that dmf-cms releases run unattended from CI? This reverses the earlier choice not to add an App or personal credential for the release gate.

Context

dmfdeploy#568 found that the dmf-cms release commit v0.38.0 reached main with no check runs at its exact commit. Two facts cause this:

• dmf-cms allows only rebase merges, so the commit on main is not the commit the pull request tested.
• Auto-merge runs as GITHUB_TOKEN. GitHub does not start workflows from events that this token causes, so the rebased commit never gets its checks.

The issue records a decision that no new personal or App credential is used. The first plan for the fix (PR #796) followed that rule. It had the release job use GITHUB_TOKEN as the bypass actor for tag creation, started the release with a manual repository_dispatch, and checked a ruleset timestamp to detect drift. Review found three problems in that design:

• The Actions bypass applies to every workflow in the repository, so no ruleset setting can limit it to the release workflow.
• The manual trigger means the release is not unattended.
• The drift check depends on API behavior that fixtures cannot establish.

Options

1. Stay attended. An operator triggers every release and publishes from a workstation. This needs no new credential and no new work, and it is not unattended.
2. One App for everything. A single App arms auto-merge and creates tags. Its key would have to be readable by the workflow that arms auto-merge, so any job that can use it can also create a release tag.
3. Two Apps, each in its own environment. One App arms auto-merge. A second App creates v* tags and is the only bypass actor on the tag ruleset. Each key lives in a GitHub environment limited to the main branch.
4. A personal access token. It ties a release to one person and carries broader scope than the task needs. We reject it.
5. A merge queue. GitHub tests the exact commit that lands on main, which removes the root cause of [dmf-cms] release tip v0.38.0 landed without required CI and guard checks #568 without an App. It does not give tag creation a scoped identity, so a tag bypass actor is still needed. We have not verified how the queue treats rebase merges on this repository.

Recommendation

Choose option 3.

• Merge. The automerge App arms auto-merge. Events from an App token start workflows, so the commit on main gets its checks. This fixes [dmf-cms] release tip v0.38.0 landed without required CI and guard checks #568 at the root.
• Release. A workflow starts from the completed CI result on main, with no inputs and no manual dispatch. It continues only when the commit is the head of main, is a release bump, and has a fresh success from every required check on that exact commit. It builds the image, checks its version and revision labels, publishes it, attaches a build-provenance attestation, and creates the tag last.
• Tag protection. A tag ruleset for refs/tags/v* allows creation only by the release App. Only a job that runs in the release environment on main can use its key.
• Permissions. The automerge App needs pull-request and contents write. The release App needs contents write. Neither gets administration or workflow permissions.
• Keys. An organization owner rotates both keys every 90 days and after any owner change, and records it in the pinned operator-notes issue.
• Residual risk. A person who can change the environment settings, or merge to main without review, is inside the trust boundary. Review rules on main and the environment branch policy limit that risk. They do not remove it.

The full design, the required tests and the rollout steps are in the plan on PR #796.

What changes

• The rule recorded in [dmf-cms] release tip v0.38.0 landed without required CI and guard checks #568 (no new personal or App credential) is replaced for this repository.
• An organization owner must create two Apps and two environments. The plan lists the steps.
• Two long-lived keys now exist, each limited to one environment.

What we have not confirmed

• That a merge armed by an App is attributed to that App and starts workflows. A probe on a disposable pull request settles this before the release trigger is enabled.
• The minimum App permissions for arming auto-merge.
• That an App can be a ruleset bypass actor in an organization on the free plan, and that attestations are available there.

Questions

• Is the extra key and rotation work acceptable for unattended releases?
• Should the same pattern later cover the other component repositories, or stay specific to dmf-cms?
• Does anyone prefer the merge queue as a first step, with the Apps added later for tag creation?

If the thread converges, an ADR follows with a one-sentence rule and an enforcement section.

[znerol2]

Update: the three items listed as unconfirmed in the post are now tested on throwaway repositories, and the results are in the plan on PR #796.

• An App-armed merge starts workflows. On a repository with rebase-only merges and a required check, a merge armed with GITHUB_TOKEN was made by the github-actions bot, and the push workflow did not run on the merged commit. That reproduces [dmf-cms] release tip v0.38.0 landed without required CI and guard checks #568. A merge armed with an App installation token was made by the App, and the push workflow ran on the merged commit.
• App permissions. An App with contents: write and pull-requests: write armed auto-merge. GitHub does not document the minimum, so the plan keeps both.
• A Free-plan organization accepts its own App as the only bypass actor on a tag ruleset. An organization admin could not create a matching tag. The App could. A workflow on a stray branch with GITHUB_TOKEN and contents: write could not. The built-in GitHub Actions integration cannot be a bypass actor at all in a personal or organization repository, so an App is the only way to scope the bypass.
• An environment limited to main withholds its secret from other branches, and a build attestation works on a Free-plan public repository.

One item stays open: whether the attestation binds to a container image digest in GHCR. The test attested a file. The first release checks this.

The test Apps are removed and the throwaway repositories are archived.

[lkirc]

I support option 3 for dmf-cms. Separating the auto-merge and tag identities gives each workflow only the authority it needs, and the exact-commit checks address the gap that prompted this RFC. The added key rotation and owner setup seem justified for unattended releases.

I would keep the plan’s pre-enable probes and checks as rollout gates, especially App-armed/direct merges, the release environment and tag ruleset behavior, and the GHCR image attestation. I favor proving this in dmf-cms before extending the pattern to other repositories.

[znerol2]

Decision: we are going ahead with option 3, two scoped GitHub Apps for unattended dmf-cms releases, as recommended in the post. Thank you for the review and the support.

Next steps:

• An ADR records the rule and its enforcement. It links this thread.
• The work lands in dmf-cms in small pull requests: push triggers so every required check runs on the merged commit, the release workflow, and the auto-merge rewrite. Each stays inert or on hold until the Apps and environments exist, and tracking stays on [dmf-cms] release tip v0.38.0 landed without required CI and guard checks #568.
• The rollout probes stay as pre-enable gates: an App-armed merge and a direct App merge, the release environment and tag ruleset behavior, the skipped-job concurrency behavior, workflow_run under the new pull_request_target policy before 2026-12-02, and the attestation on a container image digest.
• We prove the pattern in dmf-cms before we extend it to other repositories.