doc(devops): Explain how to change branch protection rules (#7883)
* Explain how to change branch protection rules * Fix list formatting * Add missing . * Fix incorrect link Co-authored-by: Pili Guerra <mpguerra@users.noreply.github.com> --------- Co-authored-by: Pili Guerra <mpguerra@users.noreply.github.com>
This commit is contained in:
parent
628b3e39af
commit
828c2aea57
|
@ -33,14 +33,18 @@ We try to use Mergify as much as we can, so all PRs get consistent checks.
|
|||
Some PRs don't use Mergify:
|
||||
- Mergify config updates
|
||||
- Admin merges, which happen when there are multiple failures on the `main` branch
|
||||
(these are disabled by our branch protection rules, but admins can remove the "don't allow bypassing these rules" setting)
|
||||
- Manual merges (these are usually disabled by our branch protection rules)
|
||||
- Manual merges (these are allowed by our branch protection rules, but we almost always use Mergify)
|
||||
|
||||
Merging with failing CI is usually disabled by our branch protection rules.
|
||||
See the `Admin: Manually Merging PRs` section below for manual merge instructions.
|
||||
|
||||
We use workflow conditions to skip some checks on PRs, Mergify, or the `main` branch.
|
||||
For example, some workflow changes skip Rust code checks. When a workflow can skip a check, we need to create [a patch workflow](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks#handling-skipped-but-required-checks)
|
||||
with an empty job with the same name. This is a [known Actions issue](https://github.com/orgs/community/discussions/13690#discussioncomment-6653382).
|
||||
This lets the branch protection rules pass when the job is skipped. In Zebra, we name these workflows with the extension `.patch.yml`.
|
||||
|
||||
### Branch Protection Rules
|
||||
|
||||
Branch protection rules should be added for every failure that should stop a PR merging, break a release, or cause problems for Zebra users.
|
||||
We also add branch protection rules for developer or devops features that we need to keep working, like coverage.
|
||||
|
||||
|
@ -55,6 +59,60 @@ When a new job is added in a PR, use the `#devops` Slack channel to ask a GitHub
|
|||
Adding a new Zebra crate automatically adds a new job to build that crate by itself in [ci-build-crates.yml](https://github.com/ZcashFoundation/zebra/blob/main/.github/workflows/ci-build-crates.yml),
|
||||
so new crate PRs also need to add a branch protection rule.
|
||||
|
||||
#### Admin: Changing Branch Protection Rules
|
||||
|
||||
[Zebra repository admins](https://github.com/orgs/ZcashFoundation/teams/zebra-admins) and
|
||||
[Zcash Foundation organisation owners](https://github.com/orgs/ZcashFoundation/people?query=role%3Aowner)
|
||||
can add or delete branch protection rules in the Zebra repository.
|
||||
|
||||
To change branch protection rules:
|
||||
|
||||
Any developer:
|
||||
|
||||
0. Run a PR containing the new rule, so its name is available to autocomplete.
|
||||
1. If the job doesn't run on all PRs, add a patch job with the name of the job.
|
||||
If the job calls a reusable workflow, the name is `Caller job / Reusable step`.
|
||||
(The name of the job inside the reusable workflow is ignored.)
|
||||
|
||||
Admin:
|
||||
|
||||
2. Go to the [branch protection rule settings](https://github.com/ZcashFoundation/zebra/settings/branches)
|
||||
3. Click on `Edit` for the `main` branch
|
||||
4. Scroll down to the `Require status checks to pass before merging` section.
|
||||
(This section must always be enabled. If it is disabled, all the rules get deleted.)
|
||||
|
||||
To add jobs:
|
||||
|
||||
5. Start typing the name of the job or step in the search box
|
||||
6. Select the name of the job or step to add it
|
||||
|
||||
To remove jobs:
|
||||
|
||||
7. Go to `Status checks that are required.`
|
||||
8. Find the job name, and click the cross on the right to remove it
|
||||
|
||||
And finally:
|
||||
|
||||
9. Click `Save changes`, using your security key if needed
|
||||
|
||||
If you accidentally delete a lot of rules, and you can't remember what they were, ask a
|
||||
ZF organisation owner to send you a copy of the rules from the [audit log](https://github.com/organizations/ZcashFoundation/settings/audit-log).
|
||||
|
||||
Organisation owners can also monitor rule changes and other security settings using this log.
|
||||
|
||||
#### Admin: Manually Merging PRs
|
||||
|
||||
Admins can allow merges with failing CI, to fix CI when multiple issues are causing failures.
|
||||
|
||||
Admin:
|
||||
1. Follow steps 2 and 3 above to open the `main` branch protection rule settings
|
||||
2. Scroll down to `Do not allow bypassing the above settings`
|
||||
3. Uncheck it
|
||||
4. Click `Save changes`
|
||||
5. Do the manual merge, and put an explanation on the PR
|
||||
6. Re-open the branch protection rule settings, and re-enable `Do not allow bypassing the above settings`
|
||||
|
||||
|
||||
### Pull Requests from Forked Repositories
|
||||
|
||||
GitHub doesn't allow PRs from forked repositories to have access to our repository secret keys, even after we approve their CI.
|
||||
|
@ -64,7 +122,7 @@ Until we [fix this CI bug](https://github.com/ZcashFoundation/zebra/issues/4529)
|
|||
1. Reviewing the code to make sure it won't give our secret keys to anyone
|
||||
2. Pushing a copy of the branch to the Zebra repository
|
||||
3. Opening a PR using that branch
|
||||
4. Closing the original PR with a note that it will be merged (this is reauired by Mergify)
|
||||
4. Closing the original PR with a note that it will be merged (closing duplicate PRs is required by Mergify)
|
||||
5. Asking another Zebra developer to approve the new PR
|
||||
|
||||
## Manual Testing Using Google Cloud
|
||||
|
|
Loading…
Reference in New Issue