Skip to content

Release Process ​

Branching Model ​

text
  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 targets main, and releases are cut from it.
  • N.x — a long-term-support (LTS) line for major version N, 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:

bash
task release:run          # main
task release:run -- 3.x   # an LTS line

The 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:

  1. semantic-release analyzes commits, determines the next version.

  2. 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.

  3. Creates a Git tag vX.Y.Z and a GitHub Release with auto-generated notes and hegemony-release.json attached as an asset.

    The notes come from scripts/release/changelog-preset.mjs: the standard angular preset with two corrections. Only numeric #123 references are linked (the generator's GitHub defaults also read a gh- prefix), and commit trailers such as Co-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 the released label (releasedLabels is off): the label is a labeled event, and ci.yml listens for those, so the label would re-run CI on every merged pull request.

  4. Updates CHANGELOG.md, bumps Python/UI/runtime version metadata, regenerates committed OpenAPI/UI contract artifacts, and generates the software bills of materials in sbom/, which are not committed: @semantic-release/github attaches them to the GitHub release. Each document's subject names blob/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.py checks the wiring: the default tagFormat, that the bump generates the documents with a timestamp, that every file the generator writes is attached, and that none is committed.

  5. 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:

    1. 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.
    2. Scan that digest. The gate is severity: CRITICAL,HIGH with ignore-unfixed: true, so a finding blocks publication only once a fixed version exists upstream. A second, non-blocking scan with ignore-unfixed: false then prints the findings that have no fix available, which the gate excludes from its output entirely.
    3. Promote the scanned digest to the release tags with docker buildx imagetools create. This writes manifest references, so the bytes behind latest are 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_REFRESH immediately before their apt-get layer. docker-publish.yml passes ${{ github.run_id }}-${{ github.run_attempt }} to refresh that layer on every release build and retry; ci-heavy.yml does 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.

  6. The demo is told (releases from main only). A notify-demo job sends a repository_dispatch (type platform-release, client_payload.version) to hegemony-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:

text
  hegemony-*-plugins ──(tag vX.Y.Z, wheels + SHA256SUMS)──▶ this repository
                                                              │ pins the tags
                                                              │ gate + manifest
                                                              ▼
                                                        hegemony-demo
                                                        (adopts the release)
  1. 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 SHA256SUMS under the tag vX.Y.Z. Every package in one of those repositories shares its SDK's version, so the SDK version is the release tag.
  2. The host pins released tags in .github/plugin-pins.json and is built and tested against exactly those commits. Its release requires the pins to be released tags — that is the gate — and publishes hegemony-release.json, the manifest of what it was built with.
  3. 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:

json
{
  "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 tag v<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:

ModeRuns whereChecks
--checkevery 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.
buildthe release, from scripts/bump-version.sh (the semantic-release prepareCmd), before anything is committed or taggedeverything 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:

text
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 tag

The 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:

json
{
  "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 of task 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:sync moves every floor to the pinned version, sets the window above it, and runs uv lock (the lockfile records the requirement strings too). Commit pyproject.toml and uv.lock on the Renovate branch.

Urgent Fixes ​

An urgent fix takes the same path as any other change, followed by a release:

  1. Branch from main: git switch -c fix/description origin/main
  2. Commit in conventional format: fix(api): description
  3. Open a pull request into main and merge it.
  4. 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):

bash
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.json that does not release from N.x, a release.yml that cannot be dispatched there, and a docker-publish.yml that would move latest.
  • 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": false in .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:

  1. Open a draft security advisory and list every supported version the vulnerability affects: the newest major and each LTS line.
  2. Prepare and review the fix for each affected branch in private, in the advisory's temporary private fork: a fix into main when the newest major is affected, and a backport into each affected N.x. Run each branch's checks before you merge it.
  3. Merge them together, then start a release on each affected branch: main as for an urgent fix, each N.x as described below.
  4. 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:

bash
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 mainRelease from N.x
Tag vX.Y.Z, GitHub release, hegemony-release.jsonYesYes
Image tags :X.Y.Z, :X.Y and the commit SHAYesYes
Image tag :latestYesNo: a tag gets it only if no higher release tag exists when its image is promoted
GitHub's "Latest" release markYesNo: @semantic-release/github publishes it with make_latest set to false
platform-release dispatch to the demoYesNo

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 prefixVersion bumpExample
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:

text
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-nflog

Tags ​

  • :latest — the newest release, decided when the scanned image is promoted: a release tag gets it only if no higher vX.Y.Z tag 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, :latest stays 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 ​

bash
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.1

Which 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/version returns version, commit and build_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_commit and build_date in 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.

bash
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.1

Check 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:

bash
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.com

The 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.

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.

RulesetTargetsEnforces
protect-main (ID 21484617)mainPull 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.

FileRulesetAdds
main.jsonrepo-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.jsonrepo-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:

sh
python3 scripts/check_ruleset_drift.py --repo hegemony-sh/hegemony --export
python3 scripts/check_ruleset_drift.py --repo hegemony-sh/hegemony

Review 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_TOKEN therefore 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 by protect-main whatever 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_TOKEN belongs 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-tags allows creating the release tag; it blocks only updates and deletion of a v* 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 ​

SecretPurposeScope
RELEASE_TOKENPAT of an organisation administrator for semantic-release to push to main past branch protectioncontents: read+write
DEMO_DISPATCH_TOKENToken that may send repository_dispatch to hegemony-demo; absent, the dispatch is skipped with a noticecontents: write on the demo repo
REPO_RULESETS_TOKENFine-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-in GITHUB_TOKEN cannot bypass rulesets, even with contents: write permission. A token whose owner is on the bypass list of every ruleset on the branch is required, and every ruleset on main and the N.x lines 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, CI and DCO, 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.

WorkflowRunner
ci.ymlCI_RUNNER
ci-heavy.yml (all jobs, docs-screenshots included)CI_RUNNER
semgrep.ymlCI_RUNNER
ruleset-drift.ymlCI_RUNNER
docker-publish.ymlCI_RUNNER
release.yml, notify-demo jobCI_RUNNER
release.yml, release jobGitHub-hosted, always
scorecard.ymlGitHub-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.yml and, 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 leave CI_RUNNER unset, 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 ​

CommandDescription
task release:run [-- N.x]Start the Release workflow on main, or on the named LTS line
task release:verify-version-syncVerify package, runtime, OpenAPI, and UI version metadata are in sync
task release:manifest:checkVerify the plugin pins, sibling checkouts and pyproject.toml version floors are consistent (offline; what CI runs on every PR)
task release:lock:checkVerify 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:buildBuild hegemony-release.json against the plugin release tags (strict; what the release runs)
task release:floors:syncMove the hegemony-* version floors to the pinned plugin versions and refresh uv.lock

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].