Release Process
Branching Model
feature/* ─●─┐ ─●─┐
▼ ▼
main ───●─────●───────●──────── (default branch)
│
v3.4.2
└── 3.x ──●──●───────── (LTS line: security fixes only)main— the default branch and the only long-lived one. Every feature and fix pull request targetsmain, and releases are cut from it.N.x— a long-term-support (LTS) line for major versionN, cut from its last release tag. Receives cherry-picked security fixes only. See Long-Term Support Lines.
How to Release
1. Start the release
Releases are started by hand. Run the Release workflow on main (Actions → Release → Run workflow), or from a checkout:
task release:run # main
task release:run -- 3.x # an LTS lineThe workflow releases the branch it is dispatched on, and stops with an error on any branch other than main or an N.x line. On main, start it once the CI push run on the latest commit is green: it covers more than the pull request checks do (the UI dependency audit, for one).
semantic-release decides the version from the commits since the branch's last release tag (see Version Determination). When none of them calls for a release (only docs, ci or chore commits, say), the run ends without one.
2. Automated release pipeline
On dispatch:
semantic-release analyzes commits, determines the next version.
The release gate runs first inside the prepare step: every plugin pin must be a released tag whose commit is the pinned one (see Release train). A pin that is not fails the release here, before anything is modified, committed or tagged. The gate writes
hegemony-release.json, the manifest of what the release was built with.Creates a Git tag
vX.Y.Zand a GitHub Release with auto-generated notes andhegemony-release.jsonattached as an asset.The notes come from
scripts/release/changelog-preset.mjs: the standardangularpreset with two corrections. Only numeric#123references are linked (the generator's GitHub defaults also read agh-prefix), and commit trailers such asCo-Authored-By:are cut from breaking-change notes, which otherwise run to the end of the commit message. Merged pull requests get the release comment but not thereleasedlabel (releasedLabelsis off): the label is alabeledevent, andci.ymllistens for those, so the label would re-run CI on every merged pull request.Updates
CHANGELOG.md, bumps Python/UI/runtime version metadata, regenerates committed OpenAPI/UI contract artifacts, and generates the software bills of materials insbom/, which are not committed:@semantic-release/githubattaches them to the GitHub release. Each document's subject namesblob/vX.Y.Z/LICENSING.md, the tag step 3 creates, so the documents are generated from the same sources as that tag.tests/deploy/test_sbom.pychecks the wiring: the defaulttagFormat, that the bump generates the documents with a timestamp, that every file the generator writes is attached, and that none is committed.docker-publish workflow publishes each of the 5 Docker images (api, ui, worker, scheduler, egress-nflog) in three steps, so that what Trivy clears is by construction what gets a release tag:
- Build and push by digest. The image is uploaded with no tag, so it is reachable only as
name@sha256:.... Nothing resolvable by tag exists in GHCR yet. - Scan that digest. The gate is
severity: CRITICAL,HIGHwithignore-unfixed: true, so a finding blocks publication only once a fixed version exists upstream. A second, non-blocking scan withignore-unfixed: falsethen prints the findings that have no fix available, which the gate excludes from its output entirely. - Promote the scanned digest to the release tags with
docker buildx imagetools create. This writes manifest references, so the bytes behindlatestare the bytes Trivy read — no rebuild, and no window in which a tag points at an unscanned image.
A green publish therefore means "nothing fixable outstanding", not "no CRITICAL/HIGH present" — the unfixable ones are in the non-blocking report. If the gate fails, the untagged manifest is simply never promoted and is collected as an unreferenced blob.
Debian package upgrades must also run when the Dockerfile has not changed. The API, worker, scheduler and egress-nflog Dockerfiles declare
SECURITY_PATCH_REFRESHimmediately before theirapt-getlayer.docker-publish.ymlpasses${{ github.run_id }}-${{ github.run_attempt }}to refresh that layer on every release build and retry;ci-heavy.ymldoes the same for the API, worker and scheduler images it scans. This prevents a cached upgrade from retaining packages that now have security fixes. The layer and its descendants rebuild, while the worker's separate Go build stages retain their caches. Local builds use the dated default; pass a new--build-arg SECURITY_PATCH_REFRESH=<value>to refresh them. An existing release tag still runs its old workflow and Dockerfiles, so release a new version containing the fix instead of retrying the old tag.- Build and push by digest. The image is uploaded with no tag, so it is reachable only as
The demo is told (releases from
mainonly). Anotify-demojob sends arepository_dispatch(typeplatform-release,client_payload.version) tohegemony-sh/hegemony-demo, whose Adopt platform release workflow pins the new release and opens its adoption pull request. See Dispatch to the demo.
semantic-release pushes the release commit (chore(release): X.Y.Z [skip ci], carrying CHANGELOG.md and the version bumps) and the tag straight to the branch it released, so nothing has to be merged back afterwards.
The release commit carries no Signed-off-by: line. Its push is not a pull request, so the DCO app does not check it. Should a pull request ever carry it (one that merges one release branch into another), it passes all the same: the DCO app skips commits made by a GitHub bot account, and the semantic-release step in .github/workflows/release.yml commits as github-actions[bot], using the numeric noreply address that ties the commit to that bot account.
The PostgreSQL CI job explicitly runs the Git inventory schema-concurrency regression alongside the shared inventory schema-cache tests. Keep new PostgreSQL-only tests in that job's file list so the default SQLite suite does not silently skip their coverage.
Release train: plugins → host → demo
Three kinds of repository release in sequence, and dependencies point one way:
hegemony-*-plugins ──(tag vX.Y.Z, wheels + SHA256SUMS)──▶ this repository
│ pins the tags
│ gate + manifest
▼
hegemony-demo
(adopts the release)- A plugin repository releases when a change merges there: its release workflow verifies every package carries the tag's version, builds the wheels, and publishes them with a
SHA256SUMSunder the tagvX.Y.Z. Every package in one of those repositories shares its SDK's version, so the SDK version is the release tag. - The host pins released tags in
.github/plugin-pins.jsonand is built and tested against exactly those commits. Its release requires the pins to be released tags — that is the gate — and publisheshegemony-release.json, the manifest of what it was built with. - The demo adopts the host release. The host dispatches an event; the demo repository downloads the manifest and re-derives its own pins from it. The host never reads anything from the demo repository — no pin, no contract test — so a demo change can never block a platform release.
Plugin pins
.github/plugin-pins.json is the single source of truth for which revision of each plugin repository the host is built against, one entry per repository:
{
"hegemony-step-plugins": {
"ref": "v0.4.0",
"commit": "5d174adef8c5c4e46f1cd4670b4746ba93910aac"
}
}"ref"records what was pinned: a tag, a branch or a SHA. Between releases it may be a branch or a merge commit while a feature is being integrated across repositories; a release requires it to be the tagv<SDK version>."commit"is the 40-hex commit that ref resolved to when it was pinned, and is what CI actually fetches (.github/actions/checkout-siblings), so a moving branch ref can never change what a pull request is tested against.
Every consumer reads this file rather than carrying its own SHA: the checkout-siblings action, scripts/dump-step-handler-types.py (the step handler catalog is generated from the pinned wheels), the two release-train scripts below, and Renovate. tests/deploy/test_ci_plugin_pins.py fails a workflow that hardcodes a sibling SHA.
Locally, keep the sibling checkouts (../hegemony-*-plugins, the layout CONTRIBUTING.md prescribes) at the pinned commits; both scripts below refuse to reason about a checkout that is somewhere else, since the versions it reports would not be the pinned ones.
The release gate and hegemony-release.json
scripts/release/build-release-manifest.py has two modes and is stdlib-only, so it runs from a bare clone with python3:
| Mode | Runs where | Checks |
|---|---|---|
--check | every pull request (CI Python Checks, task release:manifest:check) | the pins parse; the siblings are checked out at the pinned commits; the SDK and package versions are readable; the pyproject.toml version floors admit every pinned version. A ref that is not a release tag is a warning. No network. |
build | the release, from scripts/bump-version.sh (the semantic-release prepareCmd), before anything is committed or tagged | everything above as errors, plus: the ref is the tag v<SDK version>; git ls-remote shows that tag pointing at the pinned commit; the release under it publishes a wheel for every package, taken from its SHA256SUMS. Writes hegemony-release.json. |
build collects every problem before failing, and each message names the repository, the pinned ref and commit, and the tag it expected, for example:
error: hegemony-inventory-plugins: ref '10fc1fcc…' is not the release tag v0.4.0
(the tag named by packages/inventory_sdk/pyproject.toml, hegemony-inventory-sdk 0.4.0);
a release needs the pin at that tag
error: hegemony-inventory-plugins: tag v0.4.0 does not exist in
https://github.com/hegemony-sh/hegemony-inventory-plugins (pinned ref '10fc1fcc…',
commit 10fc1fccbef0); release the plugin repository first, then pin its tagThe fix is always in the same place: release the plugin repository, then move the pin to its tag (or let Renovate propose it).
The manifest (schema_version 1) is a release asset — git-ignored, never committed — listed under the @semantic-release/github plugin's assets in .releaserc.json. Its shape is a contract with the demo repository:
{
"schema_version": 1,
"platform": {
"version": "3.2.0",
"images": {
"api": "ghcr.io/hegemony-sh/hegemony/api:3.2.0",
"worker": "…", "scheduler": "…", "ui": "…", "egress-nflog": "…"
}
},
"sdks": {
"hegemony-inventory-sdk": "0.4.0", "hegemony-notification-sdk": "0.2.1",
"hegemony-secret-sdk": "0.2.0", "hegemony-step-sdk": "0.4.0"
},
"plugins": [
{
"repo": "hegemony-inventory-plugins", "tag": "v0.4.0", "commit": "<40-hex>",
"packages": [
{
"name": "hegemony-inventory-netbox", "version": "0.4.0",
"wheel": "https://github.com/hegemony-sh/hegemony-inventory-plugins/releases/download/v0.4.0/hegemony_inventory_netbox-0.4.0-py3-none-any.whl",
"sha256": "<64-hex>"
}
]
}
]
}sdks lists the SDK package under each sibling's packages/; plugins[].packages lists every other distributable package of that sibling (under plugins/, and for the step plugins also transports/ and probes/), with the name and version its pyproject.toml declares and the wheel URL and checksum from the release's SHA256SUMS. The manifest states facts about this repository and the plugins it was built with, nothing else — in particular nothing about the demo.
The plugin repositories are public, so build lists their tags and reads their release assets without a credential. It sends a token when SIBLING_REPOS_TOKEN or GITHUB_TOKEN is set, as GITHUB_TOKEN is in the semantic-release step of release.yml; the token travels as a git config environment variable and an Authorization header — never on a command line — and is scrubbed from every message the script prints.
Dispatch to the demo
After semantic-release succeeds with a new version, the notify-demo job in release.yml sends a repository_dispatch of type platform-release with client_payload.version set to the released version to hegemony-sh/hegemony-demo, using the DEMO_DISPATCH_TOKEN secret. The demo's platform-release.yml workflow receives it.
Secrets cannot be tested in an if: expression, so the job maps the secret to an environment variable and gates the step on that variable being non-empty: a fork, or a repository that has not created the secret, skips the dispatch with a notice rather than failing the release. The job has its own scope (permissions: {}, one step) so the cross-repository token is never present in the environment of npm or semantic-release.
Renovate: pin bumps and version floors
Renovate proposes plugin pin bumps from the plugin repositories' tags. A custom regex manager in .github/renovate.json reads .github/plugin-pins.json with the github-tags datasource against hegemony-sh/<repo> and semver-coerced versioning, so a pull request moves "ref" to the newest release tag and "commit" to that tag's commit in the same edit — exactly the pair the gate requires. That datasource lists tags and never branches, and the plugin pins package rule's allowedVersions admits only exact vX.Y.Z tags, so neither a branch whose name looks numeric (dependabot/uv/anyio-4.14.2) nor a prerelease can be proposed. A pin whose ref is a branch (main) or a bare SHA is not a version and is simply not updated. The four pins are grouped into one pull request, plugin pins, so the whole train is reviewed together.
The tag lookups read the plugin repositories' public tags, so the Renovate app does not need to be installed on them.
Third-party updates wait seven days after publication before Renovate proposes them (minimumReleaseAge, set repository-wide in .github/renovate.json). Docker Hub is the only registry that reports when a tag was pushed, so the wait applies there and releases without a timestamp flow as before. Vulnerability-alert fixes skip the wait, and so do the plugin pins: the plugin pins rule sets the age to null, because those tags are this organisation's own releases and the gate, not their age, vouches for them.
The hegemony-* requirements in pyproject.toml are one-minor windows, hegemony-<pkg>>=X.Y.Z,<X.(Y+1).0. [tool.uv.sources] overrides every one of them with the editable sibling checkout, so uv never enforces the range — it is the declared compatible range for an install without the override, so a separate check has to notice a pin moving past it. A hegemony-* package whose source is a path inside this repository (the registry extension, extensions/registry) has no pin: its range is checked against the version in its own pyproject.toml instead, and a name that neither a pinned sibling nor this repository ships is an error. scripts/release/sync-plugin-floors.py closes that gap:
--check(part oftask release:manifest:check, run by CI on every pull request) fails when a pinned version falls outside its declared range, or when a range is not a one-minor window. A patch release of a plugin lands green; a Renovate bump onto a new minor lands red, visibly, with the fix named in the failure and in the pull request body.task release:floors:syncmoves every floor to the pinned version, sets the window above it, and runsuv lock(the lockfile records the requirement strings too). Commitpyproject.tomlanduv.lockon the Renovate branch.
Urgent Fixes
An urgent fix takes the same path as any other change, followed by a release:
- Branch from
main:git switch -c fix/description origin/main - Commit in conventional format:
fix(api): description - Open a pull request into
mainand merge it. - Start the release on
main(task release:run).
Long-Term Support Lines
SECURITY.md publishes the support period: one major version a year becomes a long-term-support (LTS) line and receives security fixes for five years from its first release. While that major is the newest, its fixes release from main like any other. Once the next major is out, they release from the line's maintenance branch, N.x (3.x for major 3): .releaserc.json lists +([0-9]).x as semantic-release maintenance branches, and release.yml can be dispatched on them.
Create the maintenance branch
Cut N.x from the major's last release tag after the next major has been released, and protect it (see Recommended Branch Protection):
git fetch origin --tags
git switch -c 3.x v3.4.2
git push -u origin 3.x- The tag must already support maintenance releases. A workflow runs as it is in the branch or tag that triggers it, so a tag older than this support has a
.releaserc.jsonthat does not release fromN.x, arelease.ymlthat cannot be dispatched there, and adocker-publish.ymlthat would movelatest. - Creating the branch releases nothing. No push starts a release, and until a fix lands there is no commit since the tag to release.
- The branches use the default channel (
"channel": falsein.releaserc.json). Otherwise semantic-release gives each maintenance branch a channel of its own and, on the first run on a new branch, adds the tag's existing release to that channel, which runs that release's success step again. Here that step reports a new release, which can start a second publish of that version's images.
Land a security fix
A fix that reaches one supported version before the others tells everyone where to look, so all affected versions are prepared before any is released:
- Open a draft security advisory and list every supported version the vulnerability affects: the newest major and each LTS line.
- Prepare and review the fix for each affected branch in private, in the advisory's temporary private fork: a fix into
mainwhen the newest major is affected, and a backport into each affectedN.x. Run each branch's checks before you merge it. - Merge them together, then start a release on each affected branch:
mainas for an urgent fix, eachN.xas described below. - Publish the advisory once every affected version has its release, with the fixed version for each line.
When only older lines are affected, because the code is gone from the newest major or was already fixed there, fix only those N.x lines; nothing lands on main.
A backport is a pull request into N.x, where CI and the Semgrep scan run as on main:
git fetch origin
git switch -c backport/3.x/fix-description origin/3.x
git cherry-pick -x -s <fix commit>
git push -u origin backport/3.x/fix-description
gh pr create --base 3.x --title "fix(api): description"An LTS line takes three kinds of change, and nothing else:
- The security fix, and what it needs to work, such as a dependency update it requires.
- A repair that keeps the line buildable and releasable, such as a replacement for a retired base image, action or build tool.
- A fix for a regression that a security fix caused.
Use fix(...) commits for anything that changes what ships, so that the release is a patch release, and ci(...) or build(...) for repairs that do not, which release nothing on their own. Merge without squashing, or make the pull request title a fix(...) subject. semantic-release refuses a breaking change on N.x but would release a feat commit as a minor version, which the policy rules out, so review does.
When the fix is in a plugin repository, that repository releases it first and the pin on N.x moves to the new release tag, as on main: the release gate runs on N.x too.
What a maintenance release publishes
A release dispatched on N.x runs the same release job as on main: the release gate, the version bump, CHANGELOG.md, the bills of materials, the tag, the GitHub release with hegemony-release.json, and docker-publish.yml. What it leaves alone is what belongs to the newest release:
Release from main | Release from N.x | |
|---|---|---|
Tag vX.Y.Z, GitHub release, hegemony-release.json | Yes | Yes |
Image tags :X.Y.Z, :X.Y and the commit SHA | Yes | Yes |
Image tag :latest | Yes | No: a tag gets it only if no higher release tag exists when its image is promoted |
| GitHub's "Latest" release mark | Yes | No: @semantic-release/github publishes it with make_latest set to false |
platform-release dispatch to the demo | Yes | No |
Before naming the first LTS line
No LTS line is named yet. What has to hold first is tracked in TODO.md.
Whether the support period meets the Cyber Resilience Act is a separate question from these mechanics.
Version Determination
semantic-release uses Conventional Commits:
| Commit prefix | Version bump | Example |
|---|---|---|
fix(...) | PATCH (1.0.1 → 1.0.2) | fix(api): handle null device |
feat(...) | MINOR (1.0.1 → 1.1.0) | feat(ui): add device filter |
feat(...)! or BREAKING CHANGE: | MAJOR (1.0.1 → 2.0.0) | feat(api)!: rename endpoint |
Docker Images (GHCR)
Images are published to GitHub Container Registry:
ghcr.io/hegemony-sh/hegemony/api
ghcr.io/hegemony-sh/hegemony/worker
ghcr.io/hegemony-sh/hegemony/scheduler
ghcr.io/hegemony-sh/hegemony/ui
ghcr.io/hegemony-sh/hegemony/egress-nflogTags
:latest— the newest release, decided when the scanned image is promoted: a release tag gets it only if no highervX.Y.Ztag exists then. So neither a release from an LTS line nor an older release that finishes after a newer one was tagged moves it. If the newer release's images fail to publish,:lateststays on the older one until they do.:X.Y.Z— specific release version (e.g.,:1.0.1):X.Y— latest patch within minor (e.g.,:1.0):<sha>— specific commit SHA
Pull a specific version
docker pull ghcr.io/hegemony-sh/hegemony/api:1.0.1
docker pull ghcr.io/hegemony-sh/hegemony/worker:1.0.1
docker pull ghcr.io/hegemony-sh/hegemony/scheduler:1.0.1
docker pull ghcr.io/hegemony-sh/hegemony/ui:1.0.1
docker pull ghcr.io/hegemony-sh/hegemony/egress-nflog:1.0.1Which version is running
The release number lives in packages/core/version.py, which scripts/bump-version.sh rewrites on every release along with pyproject.toml and apps/ui/package.json. The publish workflow also stamps each image with the commit it was built from and the build time, as the build arguments HEGEMONY_BUILD_COMMIT and HEGEMONY_BUILD_DATE (the same values as the image's org.opencontainers.image.revision and .created labels). Images built locally, and processes run outside an image, report both as unknown.
Where to read it:
- Web UI — the bottom of the user menu shows the release and build of the API. When the browser holds a UI bundle from another build (a tab left open across an upgrade), the menu says so and offers a reload.
- API —
GET /system/versionreturnsversion,commitandbuild_date. Any signed-in caller may read it; anonymous callers get 401, because a version number tells an outsider which known vulnerabilities apply. - Logs — the API, worker and scheduler log
hegemony_version,build_commitandbuild_datein their start-up line. - Traces — every span carries
service.version.
Provenance and signature verification
An image released with signing on carries two pieces of evidence, both bound to its digest rather than to a tag: signed SLSA build provenance, kept with the repository's attestations and in the registry beside the image, and a keyless Sigstore signature made with cosign. docker-publish.yml adds them after the Trivy scan passes and before the image is tagged. Signing is switched by the SIGN_IMAGES repository variable: once it is true, every image the workflow publishes is signed and attested. Images released before it was set carry neither, and both checks below fail for them.
docker-publish.yml runs as it is in the tag it is started on. Started by hand on a tag cut before signing existed, it runs that tag's older workflow, which publishes unsigned images and moves latest. So once signing is on, do not re-run the publish for such a tag: release a new patch version instead.
Check the provenance with the GitHub CLI, naming the release tag the image was built from. Image tags drop the v of the release tag: image :1.0.1 is built from tag v1.0.1.
gh attestation verify oci://ghcr.io/hegemony-sh/hegemony/api:1.0.1 \
--repo hegemony-sh/hegemony \
--signer-workflow hegemony-sh/hegemony/.github/workflows/docker-publish.yml \
--source-ref refs/tags/v1.0.1Check the signature with cosign 3 or later; the workflow signs with cosign 3.0.6, the version its pinned sigstore/cosign-installer installs. The signing certificate names the workflow and the tag it ran for, and GitHub Actions as the token issuer:
cosign verify ghcr.io/hegemony-sh/hegemony/api:1.0.1 \
--certificate-identity https://github.com/hegemony-sh/hegemony/.github/workflows/docker-publish.yml@refs/tags/v1.0.1 \
--certificate-oidc-issuer https://token.actions.githubusercontent.comThe same two commands check the other four images under their own names. Both are bound to the repository path at publish time: an image published while this repository carried another path verifies against that path instead. The plugin repositories' release attestations follow the same rule under their own names.
Recommended Branch Protection
Branch protection for this repository is the combination of two layers. GitHub enforces every ruleset that targets a branch, so a repository ruleset can add requirements to what the organisation requires but never relax them, and a bypass granted on one ruleset does not carry over to another.
Organisation rulesets (the shared policy)
Two rulesets are managed at organisation scope (hegemony-sh → Settings → Rules → Rulesets) and apply to this repository without anything in this tree. Their canonical configuration belongs with the organisation's governance material in the hegemony-sh/.github repository, not here; the table below is a reference, checked against the live rulesets on 2026-11-06.
| Ruleset | Targets | Enforces |
|---|---|---|
protect-main (ID 21484617) | main | Pull requests only; one approving review, given after the last push; code-owner review; every review thread resolved; stale approvals dismissed on push; merge commits only; no deletion; no force pushes |
protect-release-tags (ID 21485846) | refs/tags/v* | No updates, deletion or force pushes to a release tag once it exists |
Each of them lets only organisation administrators bypass it ("always"). None of them requires a status check, and none covers the N.x LTS branches.
Repository rulesets (this repository's additions)
Kept as code under .github/rulesets/, in the JSON that "Export ruleset" writes and "Import a ruleset" reads, so a change is a reviewed change, and a workflow compares the live settings with the files every day (see Drift check). Their names start with repo- so that they cannot be mistaken for the inherited ones.
| File | Ruleset | Adds |
|---|---|---|
main.json | repo-main-checks (ID 25547476) | Required checks CI and DCO, on a branch up to date with main; one approving review, given after the last push; bypass for organisation administrators (the release push) |
lts.json | repo-lts (ID 25547507) | The full policy for the N.x lines, bypass included, mirroring the combined policy of main below, because no organisation ruleset covers them |
The files record the live rulesets in full: the id GitHub assigned at import and the settings it filled in where the import left them out (allowed_merge_methods, dismissal_restriction, required_reviewers, require_extra_approval_for_unattributed_changes, do_not_enforce_on_create). Those defaults are part of the enforced policy, so the drift check compares them too.
main.json deliberately says nothing about pull requests being required, code-owner review, thread resolution, merge methods, force pushes or deletion: the organisation rulesets enforce those, and a second copy here would be one more thing to keep in step.
The required status checks are CI, the aggregate job at the end of ci.yml that fails when any other job of that workflow failed or was cancelled (a job the changes gate skipped counts as passed), and DCO, the check the DCO GitHub App posts on every pull request.
To apply a file, go to Settings → Rules → Rulesets → New ruleset → Import a ruleset, choose the file, and create the ruleset. An import creates a new ruleset, so to change a live one, edit it in the settings and update its file in the same pull request (--export below writes the file for you); the drift check fails until the two agree. After importing or changing any ruleset, run the Scorecard workflow by hand (Actions → Scorecard → Run workflow): a ruleset change arrives on a webhook event of its own, not branch_protection_rule, so the workflow does not run on it by itself.
Drift check
ruleset-drift.yml compares the files with the live repository rulesets every day at 06:17 UTC, on a push to main that touches them, and on a manual run (Actions → Repository ruleset drift → Run workflow). A pull request runs only the offline part: the checker's tests and a validation of the files. Both jobs run on CI_RUNNER like the rest of CI (see CI Runners).
The checker, scripts/check_ruleset_drift.py, is the one the organisation runs against its own rulesets in hegemony-sh/.github (--org hegemony-sh there, --repo hegemony-sh/hegemony here). The two copies and their tests are kept identical, so a fix made in one repository is copied to the other. The checker reads the repository's own rulesets through the API (GET requests only; the inherited organisation rulesets are the organisation check's business) and compares each with its file by id: target, conditions, rules, enforcement and bypass actors included, response metadata and the order of GitHub's unordered lists excluded. A changed, missing or unrecorded live ruleset fails the run and puts a readable diff in the job summary, recorded being the file and live the settings. The checker never changes a ruleset, and a run that could not read the live settings fails with an error instead of reporting a match.
Record the live rulesets with --export, which writes their definitions into the files and nothing to GitHub: after an import, once GitHub has assigned the ids and filled in the defaults the files left out, and after a reviewed change in the settings. GitHub returns a ruleset's bypass actors only to a requester with write access to the ruleset, and the checker refuses to compare without them, so the token is a fine-grained personal access token for this repository with Administration: read and write; the checker itself only reads. With it in REPO_RULESETS_TOKEN:
python3 scripts/check_ruleset_drift.py --repo hegemony-sh/hegemony --export
python3 scripts/check_ruleset_drift.py --repo hegemony-sh/hegemonyReview the diff and commit it together with the change it records. Until a file carries its id, the check matches it by name and reports the id to record as a difference, so the first live run after an import fails on purpose. The exit codes are 0 for a match (or a completed validation or export), 1 for drift and 2 when the check could not be completed.
The workflow needs the same kind of token as a repository secret named REPO_RULESETS_TOKEN; the built-in GITHUB_TOKEN cannot see bypass actors. Without the secret the live comparison fails with an error naming it instead of passing. Replace the token there when it expires or is rotated. No credential reaches a pull request job.
Release pushes and bypass
semantic-release pushes the release commit and tag straight to main, and to an N.x branch for a maintenance release, with RELEASE_TOKEN. That push must clear every ruleset on the branch, and bypass is granted per ruleset:
- The organisation rulesets let only organisation administrators through.
RELEASE_TOKENtherefore has to be a personal access token of an organisation administrator. A GitHub App installation token, or a token of a member who is not an organisation administrator, is stopped byprotect-mainwhatever the repository rulesets say; if the token ever moves to a GitHub App, add the App to the bypass list of the organisation rulesets first. - Both repository rulesets let organisation administrators through ("Organization admin", always), recorded in their files: the same actors the organisation rulesets let through, so an administrator the organisation already trusts is never stopped by a repository ruleset alone, and
RELEASE_TOKENbelongs to one of them, so nothing is added by hand after an import. A ruleset cannot name an individual user as a bypass actor, only organisation administrators, repository roles, teams, GitHub Apps and deploy keys. A ruleset imported before the bypass was in its file lacks it until the ruleset is edited (its page → Bypass list → add "Organization admin" → Always allow); the drift check reports the difference until then. protect-release-tagsallows creating the release tag; it blocks only updates and deletion of av*tag that already exists.
The subsections below are the human-readable summary of the combined policy per branch. Change them together with the files.
main
Combined policy: protect-main (organisation) plus repo-main-checks.
- Pull requests only, merged as merge commits; no force pushes, no deletion
- Code-owner review (
CODEOWNERS), one approving review, every review thread resolved, stale approvals dismissed on push - Required status checks:
CI,DCO - Bypass: organisation administrators, on both rulesets, so that semantic-release can push the release commit and tag with
RELEASE_TOKEN, an organisation administrator's token
Required Secrets
| Secret | Purpose | Scope |
|---|---|---|
RELEASE_TOKEN | PAT of an organisation administrator for semantic-release to push to main past branch protection | contents: read+write |
DEMO_DISPATCH_TOKEN | Token that may send repository_dispatch to hegemony-demo; absent, the dispatch is skipped with a notice | contents: write on the demo repo |
REPO_RULESETS_TOKEN | Fine-grained PAT the drift check reads the live repository rulesets with, bypass actors included (GitHub shows them only to a writer of the ruleset) | administration: read+write on this repo |
Why not
GITHUB_TOKEN? GitHub Actions' built-inGITHUB_TOKENcannot bypass rulesets, even withcontents: writepermission. A token whose owner is on the bypass list of every ruleset on the branch is required, and every ruleset onmainand theN.xlines lets organisation administrators through and nobody else.
N.x (LTS lines)
Ruleset repo-lts, matching refs/heads/*.x. Rulesets match branch names with fnmatch patterns, not regular expressions, so the [0-9]+.x that the workflows' branches: filters use would not match 3.x here. *.x matches 3.x, and any other branch whose name ends in .x, so do not create one.
- The same policy as
main, written out in full in the file because no organisation ruleset covers these branches: pull requests only, merge commits, code-owner review, one approving review, every review thread resolved, stale approvals dismissed on push,CIandDCO, no force pushes - No deletion: the branch holds the line's release history
- Bypass: organisation administrators, recorded in the file, so that semantic-release can push the maintenance release commit and tag with
RELEASE_TOKEN
CI Runners
Every workflow that can run on our own hardware selects its runner through the CI_RUNNER organization/repository variable: runs-on: ${{ vars.CI_RUNNER || 'ubuntu-latest' }}. Setting it to self-hosted sends those jobs to the organization's own runners (an Ubuntu 24.04 host running eight runner services); unsetting it flips every job back to GitHub-hosted ubuntu-latest without a workflow change, which is the fallback when the host is down. GitHub-hosted runners are free for a public repository, so leaving the variable unset costs nothing.
| Workflow | Runner |
|---|---|
ci.yml | CI_RUNNER |
ci-heavy.yml (all jobs, docs-screenshots included) | CI_RUNNER |
semgrep.yml | CI_RUNNER |
ruleset-drift.yml | CI_RUNNER |
docker-publish.yml | CI_RUNNER |
release.yml, notify-demo job | CI_RUNNER |
release.yml, release job | GitHub-hosted, always |
scorecard.yml | GitHub-hosted, always |
Fork pull requests. The repository is public, so anyone can open a pull request from a fork, and the workflows that start on a pull request —
ci.yml,semgrep.ymland, when it touches the ruleset files,ruleset-drift.yml— run the version of the file the pull request carries. On a self-hosted runner that is our own host. Either leaveCI_RUNNERunset, so every job runs on a GitHub-hosted runner, or keep the runners and require approval for fork pull request workflows from all outside collaborators (Settings → Actions → General).
The release job and scorecard.yml are held back on purpose. Scorecard publishes its results only from a GitHub-hosted Ubuntu runner, so it never selects CI_RUNNER. While the repository is private its job is skipped: Scorecard cannot read a private repository with the workflow token. The release job's credential step writes RELEASE_TOKEN into the workspace's .git/config, which on a non-ephemeral runner outlives the job and is readable by every later job sharing that runner user. It runs a handful of times a month, so the minutes it would save do not pay for leaving a long-lived PAT on disk. The notify-demo job after it checks nothing out and keeps its dispatch token in its environment, so it runs on CI_RUNNER.
The host must provide what the jobs assume of ubuntu-latest: a Docker daemon the runner users may reach, passwordless sudo (the kernel egress tests, playwright install --with-deps chromium), unshare, iproute2, iptables, Chromium's system libraries, and the gh CLI (the docs-screenshots job opens its refresh PR with it). The "Free runner disk space" steps in ci-heavy's docker-scan job and docker-publish's build-and-push job are gated on runner.environment == 'github-hosted', so they never prune our own host.
A job that runs inside a container (semgrep.yml) executes as the image's user, root for semgrep/semgrep, and writes into the runner's shared workspace. Whatever it creates there stays root-owned, and the next job on that runner cannot update a ref or delete a file under a directory root made, so such a job must hand the workspace back to the runner's user in a final step that runs whether the job passed or not, as semgrep.yml does.
Every runner on the host shares one Docker daemon, so a job that names a container or tags an image puts the run id and attempt in the name, and removes what it made when it ends. Otherwise a concurrent run could reuse the name: ci.yml's object store gateway would clash with another, and its ui-image-headers job could check an image another run built. scripts/check-pq-tls.py, run by ci.yml's pq-tls-proxy job and the weekly image scan, names its containers and network at random for each run, for the same reason.
Taskfile Commands
| Command | Description |
|---|---|
task release:run [-- N.x] | Start the Release workflow on main, or on the named LTS line |
task release:verify-version-sync | Verify package, runtime, OpenAPI, and UI version metadata are in sync |
task release:manifest:check | Verify the plugin pins, sibling checkouts and pyproject.toml version floors are consistent (offline; what CI runs on every PR) |
task release:lock:check | Verify uv.lock matches pyproject.toml and the sibling checkouts: with the siblings at the pinned commits, a lock written against other sibling versions fails (what CI runs on every PR) |
task release:manifest:build | Build hegemony-release.json against the plugin release tags (strict; what the release runs) |
task release:floors:sync | Move the hegemony-* version floors to the pinned plugin versions and refresh uv.lock |