Automation, release, and security
Repository automation turns a reviewed change into a checked, versioned, and downloadable release. Pull requests receive test, changelog, dependency, secret, and workflow checks. A release then moves through a controlled sequence: release metadata is prepared, the approved release commit is tagged, platform artifacts are built from that tag, and GitHub publishes them with provenance records. This page extends Distribution and host integrations and connects to Agent and plugin packaging and Evaluation and regression suite for the package and quality surfaces used by the release.
Automation boundary
GitHub Actions is the control layer for change validation, release policy, security review, live service monitoring, and artifact delivery. Each workflow has a small permission set, and the release workflows pass state through the release label, commit message, tag, and workflow input rather than relying on an implicit handoff.
The main automation paths are:
| Path | Purpose | Main result |
|---|---|---|
| Change validation | Run product tests, Windows process checks, research evaluations, and MCP tests on pull requests and main pushes. | A change has evidence from the Python and Go parts of the product across supported runner behavior. |
| Change policy | Keep feature changes in changelog fragments and keep version surfaces aligned. | Release metadata changes happen only in a release PR. |
| Live service monitoring | Check the keyless Reddit search floor and archive hydration against live services on a daily schedule or manual run. | Service challenges are separated from parser breaks and sustained loss of the free Reddit path. |
| Security review | Check dependencies, changed dependency sets, secrets, source code, workflow safety, dependency drift, and repository security health. | Findings are blocked or published for review according to the scan. |
| Release preparation | Convert fragments into a changelog and set one new version across supported surfaces. | A labeled release PR is ready for review. |
| Release publication | Tag the merged release and build the install artifacts. | One GitHub release contains the skill and MCP packages. |
References: .github/…/validate.yml• L1-95 .github/…/changelog-guard.yml• L1-174 .github/…/reddit-canary.yml• L1-54 .github/…/prepare-release.yml• L1-131 .github/…/tag-release.yml• L1-91 .github/…/release.yml• L1-176
Change validation
The validation workflow checks the Python skill, its research quality, and the Go MCP server before a change reaches main. It also runs a Windows subprocess check because process behavior is part of the cross-platform product contract. The four checks run as separate lanes, so each produces its own result without waiting for another lane.
The checks serve different contracts:
- The Python suite checks the skill's general behavior and enforces the configured coverage floor.
- The Windows subprocess suite checks process-tree behavior on the Windows runner.
- The evaluation suite checks recorded research quality and stops at the first failing evaluation.
- The MCP suite checks the Go server and its packages under race detection.
These jobs run independently on pull requests and on pushes to main. They use read-only contents access, so validation does not also act as a release or repository mutation path.
References: .github/…/validate.yml• L1-95 pyproject.toml• L56-79
Live service monitoring
The Reddit canary is a scheduled and manual check of the free Reddit path that users receive without a login or paid key. It runs outside pull request validation because it contacts live services from a GitHub datacenter IP, where a challenge is not the same as a product failure.
For each fixed topic, the canary checks the keyless web search rungs, hydrates discovered threads through the archive path, and probes known archive thread IDs. It classifies results as working, challenged, parser-broken, or down. The workflow carries the prior verdict in the Actions cache so a loss that lasts across daily runs can be distinguished from a short service challenge.
The canary fails when a parser breaks, archive hydration is down, every discovery rung is down, or every rung remains unavailable for the configured two-day window. It saves a report and state even when the check fails, which gives later runs the context needed for the sustained-failure rule.
References: .github/…/reddit-canary.yml• L1-54 skills/…/reddit_canary.py• L1-41 skills/…/reddit_canary.py• L308-372
Changelog policy
The changelog policy separates normal product work from the act of cutting a release. Contributors describe user-facing changes in Markdown fragments under changelog.d/; a fragment can use a known issue or pull request number, or an orphan + name. The release process later combines those fragments into the generated release history in CHANGELOG.md through Towncrier.
The pull request guard applies these rules:
- A normal pull request must not edit CHANGELOG.md.
- A normal pull request must not change any lockstep version value.
- Changes to the skill engine or MCP area need a fragment unless the pull request has the
skip-changeloglabel. Fragments can describe added features, fixes, or security changes through their type suffix. - Dependabot pull requests skip the fragment requirement automatically.
- A pull request with the
releaselabel is the controlled exception for changelog and version edits.
The guard compares the pull request with the merge base of the target branch and the pull request head. This keeps the policy check tied to the actual change set even when the target branch has moved since the pull request opened. It uses the same manifest-reading rules as release preparation, so policy checks cover the version surfaces that the release process updates.
The release history keeps the Towncrier start marker and published version sections in CHANGELOG.md; contributors still add notes through fragments rather than editing those sections. The current history starts with version 4.4.0, released on 2026-11-20, and records security hardening, a Turkish README, person research, proxy mode, and related fixes under that version. The fragment contract covers more than new features. It can record fixes, security changes, and removals for the next release. These fragments are release-note inputs, not the security scans themselves; the security type records the change that users need to know about.
References: .github/…/changelog-guard.yml• L3-7 .github/…/changelog-guard.yml• L41-77 .github/…/changelog-guard.yml• L80-97 .github/…/changelog-guard.yml• L99-145 .github/…/changelog-guard.yml• L147-174 CHANGELOG.md• L1-46 changelog.d/README.md• L1-37 .github/…/read_manifest_version.py• L1-55
Security review
Security automation uses several views of risk because no single scan covers the full change. The Security workflow checks dependencies, secrets, and source code on pull requests and main pushes. Its dependency-review job runs only for pull requests. The source scan is advisory, while the dependency and verified-secret checks can block the workflow.
Other workflows extend this view beyond the current change:
| Review area | What it looks for | Enforcement or output |
|---|---|---|
| Locked dependencies | Known issues in the Python lock graph. | Fails the security workflow when the audit fails. |
| Dependency changes | New vulnerable or risky dependencies introduced by a pull request. | Runs only for pull requests and acts as a change gate. |
| Secrets | Verified secrets in the relevant change range. | Fails when a verified secret is found. |
| Source code | Security defects across the supported source and script languages. | Currently advisory; results expose issues without blocking the change. |
| Workflow configuration | Unsafe GitHub Actions patterns in the repository workflows. | Runs on pull requests and main pushes and publishes findings for review. |
| Dependency drift | Newly disclosed issues in uv.lock and mcp/go.sum. | Runs weekly or on demand and uploads advisory results to code scanning without blocking. |
| Repository security health | Signals such as token permissions, action pinning, branch protection, and workflow risk. | Runs on the default branch, branch-protection events, or a weekly schedule. It publishes a Scorecard result and keeps the raw SARIF briefly for inspection. |
The workflows keep default permissions narrow and grant write access only where a job must publish security results or release data. Actions are referenced by immutable commit pins, which lets the workflow review inspect stable action content. Scorecard measures repository-wide security health rather than a single diff. Its result is advisory and does not block merges.
References: .github/…/security.yml• L1-89 .github/…/osv-scanner.yml• L1-32 .github/…/zizmor.yml• L1-23 .github/…/scorecard.yml• L1-71 .github/dependabot.yml• L1-22
Release metadata
The project treats its version as a lockstep value across the Python package, skill metadata, plugin descriptors, marketplace entries, the MCP manifest, and the locked package record. pyproject.toml is the source used to read the current project version, while the release script updates each supported surface to the selected SemVer value.
Release metadata has two related parts:
changelog.d/holds unreleased notes. Its type names map to Keep a Changelog sections through the Towncrier configuration in pyproject.toml.- The version surfaces identify the same release to Python packaging, agent hosts, plugin marketplaces, the MCP package, and the lock file. The guard and preparation script share the list and parsing rules for these surfaces.
- The MCP manifest is part of the lockstep list. Its release artifact still receives the release tag as the binary build version, while its checked-in manifest remains the package contract used to describe the archive.
References: .github/…/changelog-guard.yml• L99-122 .github/…/prepare-release.yml• L47-95 .github/…/prepare_release.py• L22-52 .github/…/prepare_release.py• L66-164 .github/…/read_manifest_version.py• L18-38 pyproject.toml• L1-54 mcp/manifest.json• L1-31
Release preparation
The Prepare release workflow is a manual entry point for turning merged changelog fragments into a proposed version. A maintainer selects a major, minor, or patch bump, or supplies an explicit X.Y.Z version. The workflow runs the release script, creates a release/vX.Y.Z branch, and opens a pull request with the release label.
The workflow stages the generated changelog and the supported lockstep files as one release change. It also creates the release and skip-changelog labels when they do not exist, so the release pull request and the normal changelog exception use the labels expected by the policy and tag workflows.
The release script first builds CHANGELOG.md from the fragments. It then updates every lockstep version surface, including the MCP manifest, and refuses explicit downgrades or re-releases of the current version. The resulting pull request is reviewed and validated by the normal checks, while its label tells the changelog guard that these otherwise restricted edits are intentional.
This sequence makes the release pull request the review point for both release notes and version alignment. The workflow does not publish artifacts; it only prepares the commit that a later workflow can recognize safely.
References: .github/…/prepare-release.yml• L6-30 .github/…/prepare-release.yml• L38-131 .github/…/prepare_release.py• L168-217 pyproject.toml• L17-54 mcp/manifest.json• L1-31
Tag creation
The Tag release workflow watches pushes to main and acts only when the new commit has the release-preparation commit shape. It extracts the version from the commit message, confirms that the version matches pyproject.toml, finds the merged pull request, and requires that pull request to carry the repository-controlled release label.
After these checks, the workflow creates an annotated vX.Y.Z tag unless that tag already exists. It then explicitly dispatches the Release workflow. This dispatch is required because a tag pushed with the repository's GITHUB_TOKEN does not start another workflow automatically.
The tag is therefore more than a name: it is the verified handoff from the reviewed release pull request to reproducible artifact builds.
References: .github/…/tag-release.yml• L3-26 .github/…/tag-release.yml• L34-91 .github/…/prepare-release.yml• L100-131
Artifact publication
The Release workflow builds all public release artifacts from the selected tag. One job packages the existing .skill install surface. A parallel matrix builds the Go MCP server for macOS ARM64, macOS AMD64, and Linux AMD64, then places each binary in an MCPB archive with the versioned manifest from that tag.
The publication flow is:
- Resolve the release tag from a tag push or manual dispatch.
- Check out that exact tag for every build job.
- Build and attest the
.skillartifact. - Cross-compile and package each platform-specific
.mcpbartifact. - Wait for all build jobs to finish.
- Collect the artifacts and create one GitHub release with generated notes.
The build jobs attach provenance attestations before upload. The final job verifies the tag when it creates the GitHub release, which keeps the published files tied to the tagged source rather than to an arbitrary branch state.
This diagram shows the dependency from release metadata to the published files.
flowchart LR
F["changelog.d fragments"] --> P["Prepare release"]
P --> RP["release PR\nrelease label"]
RP --> M["Merge to main"]
M --> T["Tag release\nvX.Y.Z"]
T --> D["Release workflow\ntag input"]
D --> S["Build .skill"]
D --> B["Build MCPB matrix"]
S --> A["Attested artifacts"]
B --> A
A --> R["GitHub release\ngenerated notes"]
References: .github/…/release.yml• L18-55 .github/…/release.yml• L56-141 .github/…/release.yml• L143-176 mcp/manifest.json• L28-33
Change checklist
When these files or sections are changed, remember to consider these:
- When a supported version surface is added or removed, update the release script, the prepare-release staging list, and the changelog guard together. Otherwise preparation can publish a stale value or policy can stop checking a public manifest.
- When the release commit title or label policy changes, update the tag workflow and the release-preparation pull request contract together. The tag workflow must still prove that the commit came from an approved release pull request.
- When an artifact name, package layout, or MCP manifest entry point changes, update both the build job and the final release upload pattern. The archive must keep the manifest and executable paths aligned.
- When a workflow changes its permission needs or action references, keep the least-privilege grants and immutable action pins consistent with the security review workflows.
- When a new dependency lock file is added, include it in the scheduled vulnerability scan and the matching Dependabot ecosystem configuration.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A feature pull request edits CHANGELOG.md or a lockstep version. | The changelog guard rejects the pull request before release preparation. | Add a typed changelog.d fragment and leave release metadata to Prepare release. |
An engine or MCP change has no fragment and no skip-changelog label. | The pull request has no release-note contract and the guard fails. | Add a fragment or apply the deliberate skip label. |
A release-shaped commit has no merged pull request with the release label. | No version tag is created. | Use the Prepare release workflow and merge its labeled pull request. |
| pyproject.toml and the release commit version differ. | Tag creation stops before it can mint a misleading version. | Keep all release surfaces generated by the release script. |
A tag push is made by GITHUB_TOKEN without dispatch handling. | The Release workflow does not start. | Let Tag release dispatch release.yml after pushing the tag. |
| A build artifact is missing or has the wrong MCP entry path. | The final GitHub release cannot collect a usable package. | Validate the output file and the manifest-declared archive paths in the build job. |
| A verified secret or locked dependency vulnerability is found. | The security workflow fails and the change cannot pass its security gate. | Remove or update the exposed input before merge. |
| Scorecard or Semgrep finds an advisory issue. | The result is published for review without blocking the merge. | Inspect the SARIF finding and address repository-wide risk in a later change. |
Key files
| File | Why to read it |
|---|---|
| .github/…/validate.yml | Shows the baseline checks for Python behavior, Windows process behavior, research quality, and MCP behavior. |
| .github/…/changelog-guard.yml | Defines the boundary between feature changes and controlled release metadata changes. |
| .github/…/prepare_release.py | Defines version selection, changelog creation, and lockstep metadata updates. |
| pyproject.toml | Defines the project version and the Towncrier release-note contract. |
| changelog.d/README.md | Explains how contributors provide release notes without editing the generated changelog. |
| CHANGELOG.md | Shows the generated release history and the current published version entry. |
| .github/…/prepare-release.yml | Shows how a maintainer creates the labeled release pull request and stages the release metadata. |
| .github/…/tag-release.yml | Shows how a merged release commit becomes a verified version tag. |
| .github/…/release.yml | Shows how tagged source becomes attested .skill and platform MCPB artifacts. |
| mcp/manifest.json | Defines the MCP package layout and the version contract that release preparation keeps in lockstep. |
| .github/…/security.yml | Shows the per-change dependency, secret, and source-code security checks. |
| .github/…/osv-scanner.yml | Shows the scheduled and manually triggered dependency-drift scan. |
| .github/…/zizmor.yml | Shows the workflow-specific security analysis. |
| .github/…/scorecard.yml | Shows the scheduled and event-based repository security-health measurement. |