One change, every repo, tracked to merged

gh fleet is a gh extension that applies one change across many repositories and tracks the pull requests to completion.

You describe the change once, as a campaign: which repos to target, what to run in each, and how to open the PR. gh fleet clones each repo, runs your script, pushes a branch, opens the PR, and reports every PR's checks and reviews until it merges. Running the campaign again updates its PRs instead of opening new ones.

Install

gh extension install rossedman/gh-fleet

It uses your gh login (gh auth login) for the API and your own git for clones and pushes, so credential helpers, commit signing and proxies work as they do for you. If git doesn't already have GitHub credentials, run gh auth setup-git once. Prebuilt binaries for Linux, macOS and Windows (amd64 and arm64) are on the releases page, with signed checksums (how to verify). To run from source, clone the repo, make build, then gh extension install ..

Quick start

gh fleet init pin-actions --org acme   # writes a commented fleet.yaml
$EDITOR fleet.yaml                     # targets, the change script, the PR
gh fleet targets                       # which repos match, and why
gh fleet plan --repo acme/api          # run it in one clone, show the diff
gh fleet plan                          # every repo: diffs, no-ops, failures
gh fleet apply                         # push branches, open PRs (asks first)
gh fleet status                        # PR state, checks and reviews
gh fleet merge --auto                  # merge what's approved and green

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.

This is the beginning of the README. Read the rest at the original. Read the full README ↗