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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 2 additions & 7 deletions .github/workflows/dependency-scan.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,6 @@ on:
- cron: "17 6 * * 2"
workflow_dispatch:
workflow_call:
inputs:
commit:
description: Full validated commit SHA to scan
required: true
type: string
outputs:
artifact-id:
description: Immutable Actions artifact ID for this scan
Expand All @@ -25,13 +20,13 @@ jobs:
outputs:
artifact-id: ${{ steps.evidence.outputs.artifact-id }}
env:
SCAN_COMMIT: ${{ inputs.commit || github.sha }}
SCAN_COMMIT: ${{ github.sha }}
steps:
- name: Require a full commit SHA
run: '[[ "$SCAN_COMMIT" =~ ^[0-9a-f]{40}$ ]]'
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ env.SCAN_COMMIT }}
ref: ${{ github.sha }}
persist-credentials: false
- name: Confirm the checkout
run: test "$(git rev-parse HEAD)" = "$SCAN_COMMIT"
Expand Down
189 changes: 108 additions & 81 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -1,144 +1,171 @@
name: release
run-name: ${{ github.event_name == 'workflow_dispatch' && format('Prepare {0}', inputs.tag) || github.event.pull_request.title }}
run-name: ${{ github.event_name == 'pull_request' && github.event.pull_request.title || format('Release from {0}', github.sha) }}

on:
pull_request:
branches: [main]
workflow_dispatch:
inputs:
tag:
description: Existing SSH-signed PLUGIN--vVERSION tag on main
type: string
required: true
push:
branches: [main]

permissions:
contents: read

# Keep each merged release decision available for approval, even if main advances.
concurrency:
group: release-${{ inputs.tag || github.run_id }}
group: release-${{ github.event.pull_request.number || github.sha }}
cancel-in-progress: false

jobs:
validate:
runs-on: ubuntu-latest
if: github.event_name == 'pull_request'
outputs:
releases: ${{ steps.plan.outputs.releases }}
base: ${{ steps.plan.outputs.base }}
criteria: ${{ steps.plan.outputs.criteria }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.event.pull_request.head.sha }}
ref: ${{ github.sha }}
fetch-depth: 0
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- name: Validate version decisions and reviewed notes
- name: Validate version decisions and record the exact release commit
id: plan
env:
PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
PUSH_BASE_SHA: ${{ github.event.before }}
run: |
base="$(git merge-base "$PR_BASE_SHA" HEAD)"
make release-plan RELEASE_BASE="$base"
cat .cache/releases/plan.json
if git diff --quiet "$base" HEAD -- plugins/badge-buddy/assets/criteria/; then
echo "criteria=false" >> "$GITHUB_OUTPUT"
if test "$GITHUB_EVENT_NAME" = pull_request; then
base="$(git merge-base "$PR_BASE_SHA" HEAD)"
elif test "$PUSH_BASE_SHA" = 0000000000000000000000000000000000000000; then
base=empty
else
echo "criteria=true" >> "$GITHUB_OUTPUT"
base="$PUSH_BASE_SHA"
fi
- name: Verify changed criteria against the live application
if: steps.plan.outputs.criteria == 'true'
run: |
make checkout-upstream BADGE_REPO="$RUNNER_TEMP/badgeapp"
make download-criteria
make check-criteria BADGE_REPO="$RUNNER_TEMP/badgeapp"
make release-plan RELEASE_BASE="$base" RELEASE_HEAD="$GITHUB_SHA"
python3 - <<'PY'
import json
import os
import subprocess
from pathlib import Path

plan = json.loads(Path(".cache/releases/plan.json").read_text())
criteria = any(p["name"] == "badge-buddy" for p in plan["plugins"])
if plan["base"]:
difference = subprocess.run([
"git", "diff", "--quiet", plan["base"], plan["head"], "--",
"plugins/badge-buddy/assets/criteria/",
]).returncode
if difference not in (0, 1):
raise SystemExit(difference)
criteria = criteria or difference == 1
with open(os.environ["GITHUB_OUTPUT"], "a") as output:
print(f"releases={str(bool(plan['plugins'])).lower()}", file=output)
print(f"base={plan['base'] or 'empty'}", file=output)
print(f"criteria={str(criteria).lower()}", file=output)
with open(os.environ["GITHUB_STEP_SUMMARY"], "a") as summary:
print(f"## Release decision\n\nRelease source commit: `{plan['head']}`\n", file=summary)
for plugin in plan["plugins"]:
print(f"- `{plugin['tag']}`", file=summary)
if not plan["plugins"]:
print("No plugin release requested by this change.", file=summary)
else:
print("\nPublication requires passing tests, a clean dependency scan, and owner approval in the release environment.", file=summary)
PY

preflight:
if: github.event_name == 'workflow_dispatch'
checks:
needs: validate
if: github.event_name == 'push' && needs.validate.outputs.releases == 'true' && vars.RELEASE_REPOSITORY == github.repository
runs-on: ubuntu-latest
outputs:
head: ${{ steps.tag.outputs.head }}
object: ${{ steps.tag.outputs.object }}
plugin: ${{ steps.tag.outputs.plugin }}
steps:
# The workflow and helpers come from the dispatch SHA on protected main.
- name: Require the enabled repository and protected main branch
env:
ENABLED_REPOSITORY: ${{ vars.RELEASE_REPOSITORY }}
run: test "$GITHUB_REF" = refs/heads/main && test "$ENABLED_REPOSITORY" = "$GITHUB_REPOSITORY"
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.sha }}
fetch-depth: 0
persist-credentials: false
- name: Verify the tag object, signer, manifest, ancestry and notes
id: tag
env:
TAG: ${{ inputs.tag }}
ALLOWED_SIGNERS: ${{ vars.RELEASE_ALLOWED_SIGNERS }}
run: |
printf '%s\n' "$ALLOWED_SIGNERS" > "$RUNNER_TEMP/allowed_signers"
python3 -I tools/plugin_release.py verify-tag --tag "$TAG" --allowed-signers "$RUNNER_TEMP/allowed_signers" >> "$GITHUB_OUTPUT"
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- run: make check

checks:
needs: preflight
scan:
needs: validate
if: github.event_name == 'push' && needs.validate.outputs.releases == 'true' && vars.RELEASE_REPOSITORY == github.repository
uses: ./.github/workflows/dependency-scan.yml

# Advisory only: upstream changes or outages cannot veto an accepted release.
criteria:
needs: validate
if: needs.validate.outputs.criteria == 'true'
continue-on-error: true
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ needs.preflight.outputs.head }}
fetch-depth: 0
ref: ${{ github.sha }}
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- run: make check
- name: Verify Badge Buddy criteria for this release
if: needs.preflight.outputs.plugin == 'badge-buddy'
- name: Download current criteria
id: download
continue-on-error: true
run: make download-criteria
- name: Compare the accepted catalog with the current site
id: compare
if: steps.download.outcome == 'success'
continue-on-error: true
run: make compare-criteria
- name: Report advisory outcome
if: always()
env:
DOWNLOAD: ${{ steps.download.outcome }}
COMPARISON: ${{ steps.compare.outcome }}
run: |
make checkout-upstream BADGE_REPO="$RUNNER_TEMP/badgeapp"
make download-criteria
make check-criteria BADGE_REPO="$RUNNER_TEMP/badgeapp"

scan:
needs: preflight
uses: ./.github/workflows/dependency-scan.yml
with:
commit: ${{ needs.preflight.outputs.head }}
if test "$DOWNLOAD" != success; then
message='Live criteria could not be checked. Release publication is unaffected.'
echo "::warning::$message"
elif test "$COMPARISON" != success; then
message='Live criteria differ or comparison failed. Review the criteria evidence; release publication is unaffected.'
echo "::warning::$message"
else
message='The accepted criteria catalog matches the current site.'
fi
printf '## Criteria freshness (advisory)\n\n%s\n' "$message" >> "$GITHUB_STEP_SUMMARY"
- name: Preserve criteria evidence
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: criteria-advisory-${{ github.run_attempt }}
path: .cache/criteria/
include-hidden-files: true
if-no-files-found: ignore
retention-days: 14

draft:
needs: [preflight, checks, scan]
if: github.ref == 'refs/heads/main' && vars.RELEASE_REPOSITORY == github.repository
publish:
needs: [validate, checks, scan]
if: github.event_name == 'push' && github.ref == 'refs/heads/main' && needs.validate.outputs.releases == 'true' && vars.RELEASE_REPOSITORY == github.repository
environment: release
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
- name: Load the exact commit that passed verification
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ github.sha }}
fetch-depth: 0
persist-credentials: false
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
- name: Fetch dependency evidence from this run
uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
artifact-ids: ${{ needs.scan.outputs.artifact-id }}
path: ${{ runner.temp }}/evidence
merge-multiple: true
- name: Prepare the unpublished release from checked evidence
- name: Create tags, publish and verify immutable releases
env:
TAG: ${{ inputs.tag }}
OBJECT: ${{ needs.preflight.outputs.object }}
ALLOWED_SIGNERS: ${{ vars.RELEASE_ALLOWED_SIGNERS }}
RELEASE_BASE: ${{ needs.validate.outputs.base }}
GH_TOKEN: ${{ github.token }}
run: |
printf '%s\n' "$ALLOWED_SIGNERS" > "$RUNNER_TEMP/allowed_signers"
python3 -I tools/plugin_release.py draft --tag "$TAG" --allowed-signers "$RUNNER_TEMP/allowed_signers" --object "$OBJECT" --repository "$GITHUB_REPOSITORY" --evidence "$RUNNER_TEMP/evidence" --receipt "$RUNNER_TEMP/receipt.json"
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: release-subject-${{ github.run_attempt }}
path: ${{ runner.temp }}/receipt.json
if-no-files-found: error
- name: Record the maintainer finalization command
env:
TAG: ${{ inputs.tag }}
run: |
echo "Draft ready. Inspect it, then run:" >> "$GITHUB_STEP_SUMMARY"
echo "\`make release-finalize REPO=$GITHUB_REPOSITORY TAG=$TAG RUN=$GITHUB_RUN_ID\`" >> "$GITHUB_STEP_SUMMARY"
make release-publish RELEASE_BASE="$RELEASE_BASE" RELEASE_HEAD="$GITHUB_SHA" REPO="$GITHUB_REPOSITORY" RELEASE_EVIDENCE="$RUNNER_TEMP/evidence"
14 changes: 8 additions & 6 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@ UPSTREAM_REF ?=
RELEASE_BASE ?= HEAD^
RELEASE_HEAD ?= HEAD
RELEASE_PLAN ?= .cache/releases/plan.json
export TAG REPO RUN OSV_SCANNER
RELEASE_EVIDENCE ?= .cache/dependency-scan
export REPO OSV_SCANNER
RSVG ?= rsvg-convert
PNGQUANT ?= pngquant
OXIPNG ?= oxipng
Expand All @@ -38,7 +39,7 @@ PY_DIRS := $(wildcard $(foreach plugin,$(PLUGINS),$(plugin)/scripts $(plugin)/sk
.PHONY: eval-release-skills mod-test
.PHONY: format-deps hooks-install hooks-check hooks-uninstall
.PHONY: treestamp-check treestamp-update
.PHONY: download-criteria compare-criteria release-check checkout-upstream release-plan release-finalize dependency-scan
.PHONY: download-criteria compare-criteria criteria-audit release-check checkout-upstream release-plan release-publish dependency-scan

help: ## Show available targets.
@awk 'BEGIN {FS = ":.*## "; printf "Usage: make <target>\n\nTargets:\n"} /^[a-zA-Z0-9_-]+:.*## / {printf " %-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
Expand Down Expand Up @@ -124,19 +125,20 @@ checkout-upstream: setup ## Create a clean upstream clone at UPSTREAM_REF (defau
release-plan: setup ## Preview manifest version changes between RELEASE_BASE and RELEASE_HEAD.
$(VENV_PYTHON) tools/plugin_release.py plan --base "$(RELEASE_BASE)" --head "$(RELEASE_HEAD)" --output "$(RELEASE_PLAN)"

release-finalize: setup ## Verify and publish the prepared immutable draft (REPO, TAG and RUN from its Actions summary).
$(VENV_PYTHON) tools/finalize_release.py
release-publish: setup ## Publish the verified plan in the approved Actions job (REPO, RELEASE_BASE, RELEASE_HEAD).
$(VENV_PYTHON) tools/plugin_release.py publish --base "$(RELEASE_BASE)" --head "$(RELEASE_HEAD)" --repository "$(REPO)" --evidence "$(RELEASE_EVIDENCE)"

dependency-scan: setup ## Scan resolved maintainer dependencies with OSV-Scanner; save evidence under .cache/dependency-scan.
$(VENV_PYTHON) tools/scan_dependencies.py --scanner "$$OSV_SCANNER" --output .cache/dependency-scan

check-criteria: dev-deps ## Check the bundled catalog, selected checkout, and application snapshot agree.
$(VENV_PYTHON) tools/criteria_sync.py check --badge-repo "$(BADGE_REPO)" --snapshot "$(CRITERIA_SNAPSHOT)"

release-check: dev-deps ## Explicitly verify the catalog against the live site and run local checks.
criteria-audit: dev-deps ## Audit catalog freshness against the live site; advisory to release publication.
$(MAKE) download-criteria
$(MAKE) check-criteria
$(MAKE) check

release-check: check ## Run the offline release checks; live criteria freshness is advisory.

render-assets: ## Re-render and compress the PNG beside each SVG in ASSETS, or only SVG=<file>.
RSVG="$(RSVG)" PNGQUANT="$(PNGQUANT)" OXIPNG="$(OXIPNG)" tools/render-assets.sh $(if $(SVG),$(SVG),$(ASSETS))
Expand Down
14 changes: 2 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,17 +48,7 @@ Each plugin's README explains what to ask for once it is installed. Badge Buddy

<!-- treestamp:start -->
<!-- treestamp:config
hidden = [
".github", ".gitignore", ".nvmrc", ".pre-commit-config.yaml",
".prettierignore", ".prettierrc.json", "CODE_OF_CONDUCT.md",
"CONTRIBUTING.md", "LICENSE", "Makefile", "SECURITY.md",
"THIRD_PARTY_NOTICES.md", "VERIFYING.md", "package-lock.json",
"package.json", "plugins/badge-buddy/.claude-plugin",
"plugins/badge-buddy/THIRD_PARTY_NOTICES.md", "plugins/badge-buddy/assets",
"plugins/badge-buddy/scripts", "plugins/release-buddy/.claude-plugin",
"plugins/starter-buddy/.claude-plugin", "plugins/starter-buddy/scripts",
"requirements-dev.txt", "ruff.toml", "upstream-review-paths.txt",
]
hidden = [".github", ".gitignore", ".nvmrc", ".pre-commit-config.yaml", ".prettierignore", ".prettierrc.json", "CODE_OF_CONDUCT.md", "CONTRIBUTING.md", "LICENSE", "Makefile", "SECURITY.md", "THIRD_PARTY_NOTICES.md", "VERIFYING.md", "package-lock.json", "package.json", "plugins/badge-buddy/.claude-plugin", "plugins/badge-buddy/THIRD_PARTY_NOTICES.md", "plugins/badge-buddy/assets", "plugins/badge-buddy/scripts", "plugins/release-buddy/.claude-plugin", "plugins/starter-buddy/.claude-plugin", "plugins/starter-buddy/scripts", "requirements-dev.txt", "ruff.toml", "upstream-review-paths.txt"]
-->
```sh
./
Expand Down Expand Up @@ -104,7 +94,7 @@ make plugin-validate # validate each plugin's structure (needs the Claude Code
make mod-test # run the mods' tests (needs the Claude Code CLI)
```

The runtime uses only the Python standard library; the local `venv` holds the development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: bump its manifest, sign the tag, review the OSV report, then publish the immutable draft. See [Verifying a plugin release](VERIFYING.md) to check a signed release and its attachments.
The runtime uses only the Python standard library; the local `venv` holds the development dependencies. `make check` runs the plugin and maintenance suites in separate processes and compiles the Python sources. Continuous integration runs the same target on every push and pull request. See [criteria maintenance](docs/criteria-maintenance.md) for catalog updates and [plugin releases](docs/releases.md) for how to release a plugin: merge its version and reviewed notes, review the checks and OSV report, then approve publication in GitHub. The workflow tags the checked commit and publishes an immutable release. See [Verifying a plugin release](VERIFYING.md) to check its source and attachments; marketplace installation does not automatically pin or verify a release.

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to file issues and propose changes.

Expand Down
2 changes: 1 addition & 1 deletion SECURITY.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Security policy for Reponomics plugins

This policy covers the plugins in this repository, their scripts and hooks, and the release workflow and signing process.
This policy covers the plugins in this repository, their scripts and hooks, and the release workflow and verification process.

## Supported versions

Expand Down
Loading
Loading