diff --git a/.github/REPOSITORY_SETUP.md b/.github/REPOSITORY_SETUP.md index 0354f7a..8b243a2 100644 --- a/.github/REPOSITORY_SETUP.md +++ b/.github/REPOSITORY_SETUP.md @@ -20,20 +20,27 @@ owner must configure the GitHub repository after the initial `main` push. - force pushes and branch deletion disabled. Re-enable at least one independent code-owner approval after the preview, once real extension usage has informed the permanent review policy. -4. Create a GitHub App dedicated to generated publication PRs. Grant it only +4. Keep the `extension-publication` environment restricted to protected + branches. During the registry preview, configure no required environment + reviewers and disable prevent-self-review so a validated `main` dispatch can + proceed without a manual deployment approval. Add a maintainer reviewer when + the registry leaves preview, as one atomic repository-setting and + documentation change. Do not permit arbitrary selected branches or tags. +5. Create a GitHub App dedicated to generated publication PRs. Grant it only repository **Contents: read/write** and **Pull requests: read/write**. Store its App ID and private key as `CAMPUS_PUBLICATION_APP_ID` and - `CAMPUS_PUBLICATION_APP_PRIVATE_KEY` in the protected - `extension-publication` environment. Require a maintainer reviewer for that - environment, and configure its deployment-branch policy to allow only the - protected `main` branch. Do not permit arbitrary selected branches or tags. -5. Do not substitute the default `GITHUB_TOKEN` for the publication App token. + `CAMPUS_PUBLICATION_APP_PRIVATE_KEY` in the `extension-publication` + environment. Until that App is configured, a maintainer may run the same + deterministic publisher from merged `main` and open the generated PR from + their authenticated account; `verify_publication_diff.py` must pass and the + PR must contain only the catalog plus one digest-addressed artifact. +6. Do not substitute the default `GITHUB_TOKEN` for the publication App token. GitHub suppresses subsequent workflow events caused by `GITHUB_TOKEN`; the generated PR would therefore lack the required independent validation run. -6. Enable secret scanning, push protection, Dependabot alerts, and private +7. Enable secret scanning, push protection, Dependabot alerts, and private vulnerability reporting. Disable GitHub Actions from untrusted forks from receiving any secrets; the validation workflow needs read-only contents. -7. Verify the full two-PR flow with a harmless fixture release before publishing +8. Verify the full two-PR flow with a harmless fixture release before publishing a real extension. The source PR and generated artifact/catalog PR must be separate, and the latter must contain exactly two paths: the catalog and one digest-addressed artifact.