docs: clarify release flow and who can deploy what#197
Merged
Conversation
Branch protection on main now blocks non-admins from the documented `git push && git push --tags` release one-liner. Adds: - A NOTE that the one-liner only works for repo admins. - A "Releasing as a non-admin (via PR)" section showing how to bump the version on a branch, get it merged, then push the tag. - A "Who can deploy what" table summarising the permissions required for slot deploys, version bumps, tag pushes and the (currently absent) production environment gate. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the deployment documentation to reflect the current protected-branch release process and clarify which GitHub permission levels are needed for staging slot deploys and production releases.
Changes:
- Clarifies that the documented
git push && git push --tagsrelease flow only works for repo admins under branch protection. - Adds a “Releasing as a non-admin (via PR)” section describing a PR-based release workflow.
- Adds a “Who can deploy what” table summarizing permissions and current production gating behavior.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Non-admin release flow: bump package.json with `npm version --no-git-tag-version` and tag the merge commit on `main` after the PR is merged. Avoids the squash/rebase-merge pitfall where a pre-created tag would point at a commit that never lands on main. - Note that the GitHub CLI is optional and the PR can be opened from the web UI instead. - Soften the "tag must point at a commit on main" claim to a team convention — the workflow does not enforce reachability. - Reword the production environment gate row to reflect that `deploy-production.yml` does not currently declare `environment: production`, so reviewers on the Actions environment would not gate the workflow without a workflow change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The `Title, body and issue link` status check is required by branch protection on `main`, but the workflow file landing in #196 isn't on `main` yet, so this PR has no way to satisfy the check. Pulling the identical workflow file in here so the lint runs on this PR too. The file content matches #196 verbatim — when one PR merges first the other will be a no-op for this path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates release/deployment documentation to reflect branch protection constraints and contributor workflows, and introduces a PR-lint GitHub Action to enforce PR metadata requirements (title/body/test plan/issue link).
Changes:
- Document non-admin release flow via PR (version bump without tagging, then tag merge commit on
main) and clarify the admin-only one-liner. - Add a “Who can deploy what” permissions table (slots, version bump pushes, tag pushes, environment gate status).
- Add a
.github/workflows/pr-lint.ymlworkflow to validate PR title/body/issue reference and require a “## Test plan” section.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/DEPLOYMENT.adoc | Clarifies release process under branch protection and documents permissions/limitations around deploy actions. |
| .github/workflows/pr-lint.yml | Adds PR linting checks to enforce PR metadata conventions and test plan presence. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Copilot flagged two issues on this PR: 1. The workflow enforces a `## Test plan` heading, but the repo's current PR template uses `## Testing`. Without bringing the matching template change here, merging this PR before #196 would leave the lint failing for every PR opened against the live template. Pulling the updated `.github/PULL_REQUEST_TEMPLATE.md` from #196's branch so the two artefacts stay in sync. 2. The local copy of `pr-lint.yml` on this branch was a snapshot taken before the comment-rewording fix landed on #196 (ff4d6e6). Refresh from origin/chore/codeowners-pr-lint so the two branches carry identical workflow content — whichever PR merges first lands the file; the other becomes a no-op for that path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
git push && git push --tagsrelease one-liner only works for repo admins — branch protection blocks the direct push for everyone else.Test plan
N/A — docs-only change.
Notes
Title, body and issue linkcheck (added in chore: add CODEOWNERS for default review routing #196). Suggest merging chore: add CODEOWNERS for default review routing #196 first.CLAUDE.md. Out of scope here, happy to do that as a follow-up.