One change, every repo, tracked to merged

A campaign file:

apiVersion: fleet.gh/v1
name: pin-actions
targets:
  orgs: [acme]
  include:
    files: [.github/workflows]   # path must exist
  exclude:
    topics: [no-fleet]
change:
  steps:                         # run in order in one clone
    - name: find refs
      starlark: ./change.star    # load("@fleet//gha.star", "unpinned")
    - name: resolve              # shell only where a tool is needed
      run: |
        set -e
        shas=""
        for ref in ${FLEET_VAR_REFS//,/ }; do
          shas="$shas $ref=$(gh api "repos/${ref%@*}/commits/${ref#*@}" --jq .sha)"
        done
        echo "shas=$shas" >> "$FLEET_OUTPUT/vars"
    - name: pin
      starlark: ./pin.star       # load("@fleet//gha.star", "pin")
pr:
  title: "ci: pin GitHub Actions to commit SHAs"
  body: ./pr-body.md             # a Go template with .Repo and .Campaign
  labels: [fleet, security]
limits:
  maxOpenPRs: 200

The steps that edit files are Starlark, sandboxed in the clone with no shell or network. change.star lists the unpinned actions:

load("@fleet//gha.star", "unpinned")

def change(repo):
    repo.set_var("refs", unpinned(repo))

and pin.star rewrites them to the SHAs the shell step looked up:

load("@fleet//gha.star", "pin")

def change(repo):
    pin(repo, repo.vars.get("shas", ""))

The full campaign, with its test cases, is in examples/pin-actions; every example has a page on the docs site.

gh fleet plan on one repo:

$ gh fleet plan --repo acme/api
── acme/api
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e9179e8..4b6957d 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,5 +1,5 @@
 jobs:
   build:
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-go@v5
+      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4
+      - uses: actions/setup-go@0aaccfd150d50ccaeb58ebd88d36e91967a5f35b # v5

1 changed · 1 skipped

and gh fleet status once the PRs are open:

$ gh fleet status
REPO            STATUS   PR                                      CHECKS   REVIEW           NOTE
acme/api        merged   https://github.com/acme/api/pull/1      success  approved
acme/billing    pr open  https://github.com/acme/billing/pull/1  success  approved
acme/docs-site  skipped  -                                       -        -                no push access
acme/gateway    pr open  https://github.com/acme/gateway/pull/1  failure  review required
acme/web        pr open  https://github.com/acme/web/pull/1      pending  review required
acme/worker     noop     -                                       -        -

3 pr open · 1 merged · 1 noop · 1 skipped
API quota: core 4,871/5,000 · graphql 4,962/5,000

examples/ has eighty tested campaigns for the changes people make most, each a few lines of Starlark: syncing standard files, find and replace, README sections, security policies, Go, npm, Python, Cargo, Gradle, Maven, .NET and Terraform dependency bumps, Docker, Compose and Helm image bumps, runtime and runner versions, ruff and Renovate settings, Buildkite, GitLab CI, CircleCI and Jenkins pipelines, Kustomize, Argo CD, Flux and Kubernetes manifests, Terragrunt modules, changelogs, licenses, editor defaults, action upgrades and SHA pinning, pre-commit hooks, Dependabot, CODEOWNERS, .gitignore entries, read-only workflow tokens, and removing retired config.

Commands

Every command takes a campaign file (--file, default ./fleet.yaml) or the name of a campaign in local state. Read commands take --json <fields>, --jq and --template, as gh's do; see Scripting and CI for piped output and exit codes. Common flags: --repo owner/name and --repo-file (limit to some repos), --exclude owner/name and --exclude-file (leave some out), --concurrency N, --yes, --keep-workdirs, --write-rate.

How it behaves

• Idempotent. PRs are found by branch (fleet/<name>) and by a hidden marker in their body, so re-running apply updates them, and status is right even if local state is deleted. Merged PRs are skipped; closed ones are left alone unless you pass --reopen.
• Ordered steps, shell or Starlark. A change is a list of steps run in order in one clone. Each is any shell script, or a sandboxed Starlark script that edits files through a repo object with no shell or network. A built-in library (load("@fleet//gha.star", "bump_action")) covers the common edits, and your own helpers can be shared from other repos by pinned commit.
• Per-repo variables. Give repos different values (owning team, on-call channel, target version) from defaults, match rules, a CSV, or the org's custom properties. They reach scripts as FLEET_VAR_* and PR text as {{ .Vars.team }}, and a missing one fails that repo before anything is pushed.
• The script is the source of truth. An existing campaign branch is rebased onto the base; on conflict it is reset and the script runs again.
• One failure is one failure. A repo whose script fails is recorded and the rest carry on; the exit code is 1 at the end. Exit codes follow gh's: 2 when you decline a prompt, 4 when gh isn't signed in, and 8 from status --exit-status while PRs are still open.
• Kind to the API. Writes go through one shared limiter (1 per second by default), and new PRs and comments stay within GitHub's content creation limits (80 a minute, 500 an hour). A secondary rate limit pauses every worker for as long as GitHub asks, or a minute and doubling when it doesn't say; spent quota is never retried before it resets; server errors are retried with backoff; and 10% of the primary quota is kept in reserve. Org listings fetch 4 pages at a time; file checks and PR lookups are batched GraphQL queries, 50 repos at a time, split in half when GitHub times out.
• Ctrl-C is safe. The first one stops new repos from starting and lets in-flight scripts finish; state is saved. A second one exits immediately.

Configuration

Flags can also come from environment variables (GH_FLEET_CONCURRENCY, GH_FLEET_WRITE_RATE, ...) or a config file at $XDG_CONFIG_HOME/gh-fleet/config.yaml (or --config). Precedence is flag > environment > file. State lives in $XDG_STATE_HOME/gh-fleet/, with a log per repo for every script run.

The full campaign file reference, guides and command reference are on the docs site.

Contributing

See CONTRIBUTING.md. make check runs everything CI runs. Security issues: SECURITY.md.

License

Apache-2.0