Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions .github/rulesets/protect-main.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
{
"bypass_actors": [
{
"actor_id": null,
"actor_type": "OrganizationAdmin",
"bypass_mode": "always"
}
],
"conditions": {
"ref_name": {
"exclude": [],
"include": [
"~DEFAULT_BRANCH"
]
}
},
"enforcement": "active",
"name": "Protect main",
"rules": [
{
"type": "deletion"
},
{
"type": "non_fast_forward"
},
{
"parameters": {
"allowed_merge_methods": [
"merge",
"squash",
"rebase"
],
"dismiss_stale_reviews_on_push": true,
"dismissal_restriction": {
"allowed_actors": [],
"enabled": false
},
"require_code_owner_review": false,
"require_extra_approval_for_unattributed_changes": true,
"require_last_push_approval": false,
"required_approving_review_count": 1,
"required_review_thread_resolution": false,
"required_reviewers": []
},
"type": "pull_request"
},
{
"parameters": {
"do_not_enforce_on_create": false,
"required_status_checks": [
{
"context": "License headers"
}
],
"strict_required_status_checks_policy": false
},
"type": "required_status_checks"
}
],
"target": "branch"
}
25 changes: 25 additions & 0 deletions .github/rulesets/protect-tags-create.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
{
"bypass_actors": [
{
"actor_id": 5,
"actor_type": "RepositoryRole",
"bypass_mode": "always"
}
],
"conditions": {
"ref_name": {
"exclude": [],
"include": [
"~ALL"
]
}
},
"enforcement": "active",
"name": "protect-tags-create",
"rules": [
{
"type": "creation"
}
],
"target": "tag"
}
34 changes: 34 additions & 0 deletions .github/rulesets/protect-tags-immutable.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
{
"bypass_actors": [],
"conditions": {
"ref_name": {
"exclude": [],
"include": [
"~ALL"
]
}
},
"enforcement": "active",
"name": "protect-tags-immutable",
"rules": [
{
"type": "deletion"
},
{
"type": "non_fast_forward"
},
{
"parameters": {
"name": "",
"negate": false,
"operator": "regex",
"pattern": "^v\\d+\\.\\d+\\.\\d+(-[0-9A-Za-z.-]+)?$"
},
"type": "tag_name_pattern"
},
{
"type": "update"
}
],
"target": "tag"
}
60 changes: 60 additions & 0 deletions .github/workflows/rulesets.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

# Compares .github/rulesets/*.json with the rulesets live on GitHub.
# See docs/rulesets.md. Actions are pinned by commit SHA (version in the
# trailing comment).
name: rulesets

on:
# Show reviewers what a ruleset change would do once applied.
pull_request:
branches: [main]
paths:
- '.github/rulesets/**'
- '.github/workflows/rulesets.yaml'
- 'scripts/apply-rulesets.sh'
# Fail when the live rulesets drift from the files, for example after a
# merged change that no admin has applied yet, or an edit in the UI.
schedule:
- cron: '0 7 * * *' # every day at 07:00 UTC
workflow_dispatch:

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

permissions:
contents: read

jobs:
rulesets:
name: Rulesets match the repository
runs-on: ubuntu-24.04 # pinned: ubuntu-latest moves to 26.04 from 2026-10-19; bump deliberately
timeout-minutes: 5
env:
GH_TOKEN: ${{ github.token }}
REPO: ${{ github.repository }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false

- name: Show differences from the live rulesets
if: github.event_name == 'pull_request'
run: scripts/apply-rulesets.sh --dry-run

- name: Check for drift from the live rulesets
if: github.event_name != 'pull_request'
run: scripts/apply-rulesets.sh --check
53 changes: 53 additions & 0 deletions docs/rulesets.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Repository rulesets

GitHub [rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)
enforce how changes reach `main` and who can create release tags. They are kept
in this repository, in [`.github/rulesets/`](../.github/rulesets), so a change
to them is proposed, reviewed and recorded like any other change.

## What is enforced

| Ruleset | Applies to | Rules | Who can bypass |
|---|---|---|---|
| [`Protect main`](../.github/rulesets/protect-main.json) | `main` (`~DEFAULT_BRANCH`) | No deletion or force-push. Changes go through a pull request with 1 approving review, and a new push clears earlier approvals. The `License headers` check must pass. | Organization admins |
| [`protect-tags-create`](../.github/rulesets/protect-tags-create.json) | All tags | Tags can't be created. | Repository admins, who are the only ones able to push a release tag |
| [`protect-tags-immutable`](../.github/rulesets/protect-tags-immutable.json) | All tags | Once created, a tag can't be moved or deleted, and names must match `vMAJOR.MINOR.PATCH[-PRERELEASE]`. | Nobody |

The JSON files are the source of truth. If this table and a file disagree, the
file wins.

## Changing a ruleset

1. Edit or add a file in `.github/rulesets/`. Each file holds one ruleset, in
the format of the [rulesets REST API](https://docs.github.com/en/rest/repos/rules),
with only the policy fields: `name`, `target`, `enforcement`, `conditions`,
`rules` and `bypass_actors`. The file name is the ruleset name in lower
case with dashes, for example `protect-main.json` for `Protect main`.
2. Open a pull request. The **rulesets** workflow runs
`scripts/apply-rulesets.sh --dry-run` and prints how the change differs from
what is live.
3. After the pull request is merged, a repo admin applies it:

```bash
scripts/apply-rulesets.sh --dry-run # review the differences
scripts/apply-rulesets.sh # create or update the live rulesets
```

Rulesets are matched by name. The script never deletes a live ruleset; it
lists live rulesets that have no file, and an admin deletes them in
**Settings → Rules → Rulesets** once they are no longer needed.

New or stricter rulesets should start with `"enforcement": "evaluate"`. Once
the rule insights (**Settings → Rules → Insights**) show that they wouldn't
block legitimate work, a follow-up pull request switches them to `"active"`.

## Drift

The **rulesets** workflow also runs `scripts/apply-rulesets.sh --check` every
day. It fails when a live ruleset differs from its file, when a file hasn't
been applied, or when a live ruleset has no file. The fix is either to apply
the files, or, if the live change was intended, to export it with
`scripts/apply-rulesets.sh --export` and open a pull request.

Only admins can read a ruleset's `bypass_actors`. For everyone else, including
the workflow, GitHub hides them, so they are left out of the comparison.
Loading