Setting up the auto-stamp GitHub App

This playbook is the auditable record of how the auto-stamp App was created on the BioFlow Pro repo and what authority it carries. Follow it end-to-end when standing up TRACE ALM on a new project; the only per-project changes are the App’s name and the org / repo it targets.

Last verified against GitHub UI as of 2026-04-28. Update this date and any wording that has drifted on each subsequent review.

What this sets up

Component	Identity
Org-owned GitHub App	bioflow-autostamp (in the Corona-Project-Life org)
Installed on	Corona-Project-Life/Bioflow-Pro only
Permissions	Repository: Contents (read/write), Pull requests (read), Metadata (read)
Branch-protection bypass	App added to the main branch’s bypass list
Repo secrets	AUTOSTAMP_APP_ID, AUTOSTAMP_APP_PRIVATE_KEY

Prerequisites

• Org-admin access on the Corona-Project-Life GitHub org (only an admin can create org-owned Apps and configure branch protection bypass lists)
• The repo’s .github/CODEOWNERS and .github/workflows/auto-stamp.yml already merged on main (this playbook configures the App that consumes them)

Step 1 — Create the GitHub App in the org settings

Go to the organisation settings page (not the user-personal page — the App must be owned by the org so its installation scope is the org’s repos):

https://github.com/organizations/Corona-Project-Life/settings/apps

Click New GitHub App. Fill in:

Field	Value
GitHub App name	bioflow-autostamp
Homepage URL	https://github.com/Corona-Project-Life/Bioflow-Pro
Webhook → Active	uncheck (the App is not a webhook consumer)
Identifying and authorizing users section	Leave all defaults; do not set a Callback URL, do not enable OAuth or Device Flow

The “Identifying and authorizing users” section is for Apps that act on behalf of a user via OAuth login flows. The auto-stamp Action acts as the App itself using a server-to-server installation token, so none of those options apply.

Permissions

Set the following repository permissions; leave every other permission at “No access”:

Permission	Access
Contents	Read and write
Pull requests	Read
Metadata	Read (selected by default; cannot be unset)

Leave organization and account permission sections fully at “No access”.

Where can this GitHub App be installed?

Select Only on this account. Because the App is being created from the org’s settings page, “this account” means the Corona-Project-Life organisation — the App can only be installed on repos in that org, not on personal accounts or other orgs.

Click Create GitHub App.

Step 2 — Generate the App’s private key

On the App’s settings page (after creation), scroll to Private keys → click Generate a private key. Your browser will download a .pem file. Keep it accessible for the next steps; we’ll discard it after copying its contents into the repo secrets.

Step 3 — Install the App on the BioFlow Pro repo

On the App’s settings page, click Install App in the left sidebar. Next to the Corona-Project-Life org, click Install. On the resulting page:

1. Select Only select repositories
2. Choose Bioflow-Pro
3. Click Install

The App is now installed on this one repo.

Step 4 — Add the App to the branch-protection bypass list

The App needs permission to push directly to main (which is protected). Go to:

https://github.com/Corona-Project-Life/Bioflow-Pro/settings/branches

If the repo uses classic branch protection rules:

1. Edit the rule for main
2. Find Allow specified actors to bypass required pull requests
3. Enable it and add the bioflow-autostamp App (it appears as an “Apps” actor type once installed)
4. Save

If the repo uses rulesets (newer system):

1. Go to Settings → Rules → Rulesets
2. Edit the ruleset that targets main
3. Find Bypass list
4. Add bioflow-autostamp (Apps category)
5. Save

The generic github-actions[bot] is not added to the bypass list. Only bioflow-autostamp can push to main outside of the PR flow.

Step 5 — Add the repo secrets

Go to:

https://github.com/Corona-Project-Life/Bioflow-Pro/settings/secrets/actions

Click New repository secret and add two:

Secret name	Value
AUTOSTAMP_APP_ID	The numeric App ID shown at the top of the App’s settings page (a 6–7 digit number)
AUTOSTAMP_APP_PRIVATE_KEY	The entire contents of the .pem file from Step 2 (open in a text editor, copy from -----BEGIN PRIVATE KEY----- through -----END PRIVATE KEY----- inclusive, paste into the secret value)

After this, delete the local .pem file from your machine. It is no longer needed; the secret store has it, and a new key can be regenerated on the App’s settings page if ever required.

Step 6 — Enable “Require review from Code Owners”

Same branch-protection page as Step 4. Toggle Require review from Code Owners ON. Save.

The .github/CODEOWNERS file is already in place from a prior commit; this toggle is what enforces it. Until this toggle is on, CODEOWNERS is informational only — GitHub auto-requests the listed reviewers but does not block merges.

Step 7 — Verify

Open a small test PR that touches any one of regulatory-docs/10_system.sdoc, regulatory-docs/11_srs.sdoc, or regulatory-docs/20_architecture.sdoc (any small whitespace change is enough). Confirm:

1. The PR check shows that boss (@DougYoungberg, per CODEOWNERS) is requested as reviewer
2. The PR cannot be merged until boss approves (branch protection enforces this)
3. After merge, the Auto-stamp REVIEWED_HASH workflow appears in the Actions tab and runs to completion
4. A new commit on main authored by bioflow-autostamp[bot] updates REVIEWED_HASH and REVIEWED_BY on the touched requirement

If any of those four steps fail, see the auto-stamp tooling page for failure modes and recovery.

What this playbook records

The fields above are not a generic GitHub-App tutorial — they are the specific configuration the BioFlow Pro repo runs on. Future auditors and external reviewers can compare this playbook against the App’s settings page in the org and verify that nothing has drifted.

If any field changes (App name, permissions, install scope, bypass list members, secret names), update this playbook in the same PR that changes the configuration. Drift between this playbook and reality is a Part 11 control-failure flag in its own right.