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
87 changes: 58 additions & 29 deletions .github/workflows/update-catalog.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,54 +14,83 @@ on:
description: Release tag to publish
required: true
type: string
allow_rollback:
description: Accept a version that is not newer than the listed one (deliberate rollback only)
required: false
type: boolean
default: false

permissions:
contents: write
# CATALOG_PUSH_TOKEN pushes the catalog, and every approved repository is
# public, so the workflow token needs no permissions.
permissions: {}

concurrency:
group: plugin-catalog-update
cancel-in-progress: false
# No concurrency group. A group keyed on the dispatch payload lets anyone with
# the dispatch token cancel a plugin's pending run by sending bogus dispatches,
# since GitHub keeps one pending run per group. Runs instead race on the push:
# each attempt below rebuilds on the current main, and update-catalog re-checks
# the version against it, so a duplicate run becomes a no-op and an older
# release that loses to a newer one is refused.

jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
token: ${{ secrets.CATALOG_PUSH_TOKEN }}

- uses: actions/setup-go@v6
- uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
with:
go-version: "1.26"

- name: Update catalog manifest
- name: Test catalog tooling
env:
GOWORK: "off"
run: go test ./...

- name: Update, validate, and push the catalog
env:
GOWORK: "off"
GITHUB_TOKEN: ${{ github.token }}
PLUGIN_REPO: ${{ inputs.repo || github.event.client_payload.repo }}
PLUGIN_TAG: ${{ inputs.tag || github.event.client_payload.tag }}
# Only a manual run can roll back; a repository_dispatch payload
# cannot set this.
ALLOW_ROLLBACK: ${{ github.event_name == 'workflow_dispatch' && inputs.allow_rollback }}
run: |
test -n "$PLUGIN_REPO"
test -n "$PLUGIN_TAG"
go run ./cmd/update-catalog -repo "$PLUGIN_REPO" -tag "$PLUGIN_TAG"

- name: Validate approved catalog
env:
GOWORK: off
run: |
go test ./...
go run ./cmd/check-catalog

- name: Commit catalog changes
env:
PLUGIN_REPO: ${{ inputs.repo || github.event.client_payload.repo }}
PLUGIN_TAG: ${{ inputs.tag || github.event.client_payload.tag }}
run: |
if git diff --quiet -- manifest.json; then
exit 0
fi
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add manifest.json
git commit -m "chore: update catalog for ${PLUGIN_REPO}@${PLUGIN_TAG}"
git pull --rebase origin main
git push origin HEAD:main
args=(-repo "$PLUGIN_REPO" -tag "$PLUGIN_TAG")
if [ "$ALLOW_ROLLBACK" = "true" ]; then
args+=(-allow-rollback)
fi
# update-catalog validates the repository and tag, refuses a
# repository outside approved-plugins.json, a version not newer than
# the listed one, drafts and prereleases, asset URLs outside the
# release, and an unsigned release of a plugin whose entry is signed.
# It verifies a signed release's binaries with gh attestation verify
# and reads manifest.json at the release's commit.
# A repository_dispatch run checks out main as it was when the release
# fired, and other releases may have updated the catalog since. Each
# attempt rebuilds the entry on the current main, so losing a push race
# retries instead of conflicting on manifest.json.
for attempt in 1 2 3 4 5; do
git fetch --quiet origin main
git reset --quiet --hard FETCH_HEAD
go run ./cmd/update-catalog "${args[@]}"
if git diff --quiet -- manifest.json; then
echo "The catalog already lists ${PLUGIN_REPO}@${PLUGIN_TAG}."
exit 0
fi
go run ./cmd/check-catalog
git add manifest.json
git commit --quiet -m "chore: update catalog for ${PLUGIN_REPO}@${PLUGIN_TAG}"
if git push origin HEAD:main; then
exit 0
fi
sleep $((attempt * 5))
done
echo "Could not push the catalog update after 5 attempts." >&2
exit 1
18 changes: 18 additions & 0 deletions APPROVAL_POLICY.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,24 @@ An approved community plugin must satisfy all of the following at review time:
Approval records the evidence URL and date in `approved-plugins.json`. A release
dispatch cannot approve a repository by itself.

## Release signing

Signed releases of an approved plugin must be signed by Silo's shared release
workflow (`Silo-Server/.github`, `plugin-release.yml` at `main`) unless its
registry entry sets `signer_workflow`. That optional field names one workflow
file in the plugin's own repository, as a plain file name ending in `.yml` or
`.yaml` (for example `"signer_workflow": "release.yml"`). When it is set, the
catalog accepts only that workflow, run from the release tag, for a commit on
the repository's default branch, and no longer accepts the shared workflow for
that plugin.

Setting `signer_workflow` is an approval decision. The shared workflow fixes the
build steps; a plugin's own workflow lets its maintainers change them. Before
setting it, a reviewer checks that the named workflow builds and attests the
release binaries, runs only on GitHub-hosted runners, and is triggered by
release tags, and that the repository protects its default branch. Approval
records this review the same way as the original approval.

Approval may be withdrawn if the plugin becomes unsafe, misleading,
unmaintained, or incompatible. Removing it from the registry and regenerating
the catalog stops new installs and update discovery. Silo does not remotely
Expand Down
51 changes: 51 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Contributing to the Approved Community Plugin Catalog

This repository holds the catalog of approved community plugins and the tooling
that builds it. Plugin implementation changes belong in the plugin's own
repository. Approval requests and the review rules are covered by
[`APPROVAL_POLICY.md`](APPROVAL_POLICY.md).

## Before you start

Open an [issue](https://github.com/Silo-Community/silo-plugins/issues) before
changing catalog schema, the approval registry format, release ingestion,
signature policy, or automation.

Catalog entries are generated from a plugin's published GitHub release by the
update workflow. Do not hand-edit `manifest.json` to work around a missing or
incorrect upstream artifact. Changes to `approved-plugins.json` follow the
approval policy and are reviewed by its code owner.

## Development setup

Use the Go version declared in `go.mod`. The update command reads release assets
from GitHub, so use a real tagged release when testing ingestion, and run it
against a copy of `manifest.json` as the README shows. Never place tokens in
command arguments, committed files, or logs.

## Validate your change

```sh
GOWORK=off go test ./...
GOWORK=off go vet ./...
GOWORK=off go build ./...
GOWORK=off go run ./cmd/check-catalog
gofmt -l .
```

`gofmt -l .` should print nothing. For catalog output changes, inspect the
complete `manifest.json` diff and verify repository URLs, versions, platforms,
the checksum URL, the bundle URL when the release is signed, capabilities,
presentation metadata, and approval metadata against the source release and
the registry.

Changes to `update-catalog`'s refusal rules (input validation, the approval
registry lookup, version order, asset URLs, the commit binding, or signature
policy) need a unit test for each refusal in `catalog/catalog_test.go`.

## Open the pull request

Use a Conventional Commit title, explain the catalog or automation impact, and
paste the actual validation results. Disclose AI assistance as the
[AI-assisted contribution policy](https://github.com/Silo-Server/silo-server/blob/main/docs/ai-contributions.md)
describes.
113 changes: 110 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,114 @@ can publish entries. See [`APPROVAL_POLICY.md`](APPROVAL_POLICY.md) for the
review requirements.

After an approved plugin publishes a checksum-bearing GitHub release, its
release workflow dispatches `plugin_release_published` to this repository. The
catalog updater verifies the repository and plugin ID against the approval
registry before updating `manifest.json`.
release workflow dispatches `plugin_release_published` to this repository.

## Catalog updates

`update-catalog` refuses a release unless all of these hold, and writes
`manifest.json` only after the last check:

- The repository is `owner/name` and the tag is `v<major>.<minor>.<patch>`,
optionally with a `-suffix`. Both are checked before either goes into a URL.
- The repository is listed in `approved-plugins.json`, spelled exactly as it is
there, and the release's `manifest.json` names the plugin ID approved for it.
A dispatch cannot add a repository or change which plugin it publishes.
- The version is newer than the plugin's listed version. Re-running for the
listed version does nothing and succeeds. A deliberate rollback needs the
`allow_rollback` input of a manual `workflow_dispatch` run; a
`repository_dispatch` cannot set it.
- The release is published for exactly that tag and is neither a draft nor a
prerelease. There is no override for drafts or prereleases.
- Every catalogued asset URL (the `plugin-<os>-<arch>` binaries,
`checksums.txt`, and `plugin.sigstore.json`) is
`https://github.com/<repo>/releases/download/<tag>/<asset name>`. Other
release assets, such as `.zip` archives, are ignored.

`manifest.json` is read at a commit SHA, never at the tag name: the commit the
signature names for a signed release, or the commit the tag points at
(following an annotated tag) for an unsigned one.

Entries whose plugin is no longer in `approved-plugins.json` are removed the
next time the catalog is written.

### Signed releases

A signed release carries `plugin.sigstore.json`: a Sigstore bundle with one SLSA
provenance attestation covering every `plugin-<os>-<arch>` binary. Before
writing the entry, `update-catalog` downloads every binary and checks it with
`gh attestation verify`. The entry then gains a package-level `bundle_url`
beside `checksums_url`, and each binary gains a `checksum`: the SHA-256 of the
file the tool verified. Silo servers prefer that checksum over `checksums_url`,
so the listed bytes stay pinned even if the release assets are replaced later.
Unsigned entries carry no per-binary checksum.

The certificate must name exactly one signer, chosen by the plugin's entry in
`approved-plugins.json`:

- By default, Silo's shared release workflow,
`https://github.com/Silo-Server/.github/.github/workflows/plugin-release.yml@refs/heads/main`.
No other workflow is accepted.
- If the entry sets `signer_workflow` (for example `"signer_workflow":
"release.yml"`), that workflow file in the plugin's own repository, run from
the release tag:
`https://github.com/<repo>/.github/workflows/<signer_workflow>@refs/tags/<tag>`.
The shared workflow is then not accepted for that plugin. The signed commit
must also be on the repository's default branch: GitHub's compare API must
report it as identical to or behind that branch, not ahead or diverged.

For both signers, the tool also requires the issuer
`https://token.actions.githubusercontent.com`, the approved repository as the
source repository, the source ref `refs/tags/<tag>`, a GitHub-hosted runner,
SLSA provenance v1, a Sigstore public-good transparency-log entry, and the same
source commit for every binary. Any failure refuses the release.

What a signature proves:

- Shared workflow: the binaries were built on a GitHub-hosted runner by Silo's
release workflow at `main`, from the approved repository at the commit the
release tag named. The build steps are Silo's, not the plugin's. It does not
prove the plugin's source at that commit was reviewed.
- Own workflow: the binaries were built on a GitHub-hosted runner by the named
workflow file, as it existed at the tagged commit, from a commit already on
the default branch. Anyone who can push to the default branch and create
tags can change that workflow and what it builds, so this proves origin from
the approved repository's default branch, not that the build steps or source
were reviewed.

Unsigned releases are still accepted for a plugin until its catalog entry has a
`bundle_url`; after that, an unsigned release of that plugin is refused.
`signer_workflow` is an approval decision; see
[`APPROVAL_POLICY.md`](APPROVAL_POLICY.md). `check-catalog` validates its format.

### Workflow

The update workflow has no concurrency group. Runs race on the push, and each
attempt rebuilds the entry on the current `main` and runs `check-catalog`, so a
duplicate run is a no-op and an older release that loses the race to a newer
one is refused. `CATALOG_PUSH_TOKEN` pushes the update; the workflow's own
token has no permissions, because every approved repository is public.

### Running it locally

Pass the repository in `owner/name` form and the exact release tag. Verifying a
signed release needs the `gh` CLI on `PATH`. To try the tool against a release
the catalog already lists, rebuild that entry in a copy of the catalog:

```sh
catalog_copy="$(mktemp)"
cp manifest.json "$catalog_copy"
GOWORK=off go run ./cmd/update-catalog \
-repo Silo-Community/silo-plugins-requests-arr \
-tag v0.1.11 \
-allow-rollback \
-manifest "$catalog_copy"
diff manifest.json "$catalog_copy"
```

Without `-allow-rollback`, the listed version does nothing and an older one is
refused.

## Development

Validate the registry and generated catalog locally with:

Expand All @@ -33,6 +138,8 @@ GOWORK=off go test ./...
GOWORK=off go run ./cmd/check-catalog
```

See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## License

The catalog tooling is licensed under `Apache-2.0`. See [LICENSE](LICENSE).
34 changes: 34 additions & 0 deletions catalog/approval.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,15 @@ import (
"encoding/json"
"fmt"
"net/url"
"regexp"
"strings"
"time"
)

// signerWorkflowPattern is a plain workflow file name in .github/workflows:
// no path separators, no leading dot, and a .yml or .yaml extension.
var signerWorkflowPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*\.ya?ml$`)

type Approval struct {
ApprovedAt string `json:"approved_at"`
ReviewURL string `json:"review_url"`
Expand All @@ -18,6 +23,10 @@ type ApprovedPlugin struct {
Repository string `json:"repository"`
ApprovedAt string `json:"approved_at"`
ReviewURL string `json:"review_url"`
// SignerWorkflow, when set, names the one workflow file in the plugin's
// own repository whose signature the catalog accepts instead of Silo's
// shared release workflow. Setting it is an approval decision.
SignerWorkflow string `json:"signer_workflow,omitempty"`
}

type ApprovalRegistry struct {
Expand Down Expand Up @@ -56,6 +65,9 @@ func DecodeApprovalRegistry(data []byte) (ApprovalRegistry, error) {
if err := validateGitHubURL(plugin.ReviewURL); err != nil {
return ApprovalRegistry{}, fmt.Errorf("review_url for %s: %w", pluginID, err)
}
if plugin.SignerWorkflow != "" && !signerWorkflowPattern.MatchString(plugin.SignerWorkflow) {
return ApprovalRegistry{}, fmt.Errorf("signer_workflow for %s must be a .yml or .yaml file name with no path, got %q", pluginID, plugin.SignerWorkflow)
}
seenPluginIDs[pluginID] = struct{}{}
seenRepositories[repositoryKey] = struct{}{}
}
Expand All @@ -71,6 +83,28 @@ func (r ApprovalRegistry) Resolve(repository, pluginID string) (Approval, error)
return Approval{}, fmt.Errorf("plugin %s from %s is not approved", pluginID, repository)
}

// ApprovedRepository returns the registry entry for repo, or an error when
// repo is not approved. update-catalog calls it before any fetch. The
// comparison is exact, so every request and asset URL built from repo uses the
// spelling the registry records.
func (r ApprovalRegistry) ApprovedRepository(repo string) (ApprovedPlugin, error) {
for _, approved := range r.Plugins {
if approved.Repository == repo {
return approved, nil
}
}
return ApprovedPlugin{}, fmt.Errorf("repository %s is not in the approval registry", repo)
}

// CheckManifestPluginID refuses a release whose manifest.json names a plugin
// other than the one approved for its repository.
func (a ApprovedPlugin) CheckManifestPluginID(got string) error {
if got != a.PluginID {
return fmt.Errorf("manifest.json names plugin %q, but %s is approved for %q", got, a.Repository, a.PluginID)
}
return nil
}

func ValidateApprovedIndex(index RepositoryIndex, registry ApprovalRegistry) error {
seenPluginIDs := make(map[string]struct{}, len(index.Plugins))
for _, pkg := range index.Plugins {
Expand Down
Loading
Loading