diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..cb814fe --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,15 @@ +version: 2 +updates: + + # Covers actions/* and other tagged refs that appear in workflows here. + # + # It does NOT maintain the PerlToolsTeam/github_workflows SHA pins in + # ci.yml. Dependabot only advances a SHA-pinned ref when the upstream repo + # publishes tags (dependabot-core github_actions/update_checker.rb, + # latest_commit_sha returns early without a latest_version_tag), and that + # repo has none. Those pins must be reviewed by hand -- see + # docs/ci-pin-maintenance.md. + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c62244f..654a938 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,16 +8,28 @@ on: workflow_dispatch: jobs: + # Calls the cpan-test composite action directly rather than the cpan-test.yml + # reusable workflow: the latter fixes its own matrix strategy at the default + # fail-fast: true, which cancels healthy cells when an unrelated one fails and + # makes per-platform results unreadable. test: - uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-test.yml@main - with: - os: '["ubuntu-latest"]' - perl_version: '["5.24", "5.30", "5.36", "5.40"]' + runs-on: ${{ matrix.os }} + name: Perl ${{ matrix.perl }} on ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ ubuntu-latest, macos-latest, windows-latest ] + perl: [ "5.24", "5.30", "5.36", "5.40" ] + steps: + - uses: PerlToolsTeam/github_workflows/.github/actions/cpan-test@b4ba4e5553820e802da91d58eba295575945ad95 # main @ 2026-06-23 + with: + perl_version: ${{ matrix.perl }} + os: ${{ matrix.os }} coverage: - uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-coverage.yml@main + uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-coverage.yml@b4ba4e5553820e802da91d58eba295575945ad95 # main @ 2026-06-23 perlcritic: - uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-perlcritic.yml@main + uses: PerlToolsTeam/github_workflows/.github/workflows/cpan-perlcritic.yml@b4ba4e5553820e802da91d58eba295575945ad95 # main @ 2026-06-23 with: level: 5 diff --git a/docs/ci-pin-maintenance.md b/docs/ci-pin-maintenance.md new file mode 100644 index 0000000..6ce88bc --- /dev/null +++ b/docs/ci-pin-maintenance.md @@ -0,0 +1,65 @@ +# CI pin maintenance + +`.github/workflows/ci.yml` pins every `PerlToolsTeam/github_workflows` +reference to a commit SHA rather than `@main`. + +## Why pinned + +Tracking `@main` meant upstream could change this repository's CI with no +commit here. That is not hypothetical: PDF-Reuse lost Windows CI for six +months to an upstream regression, and the eventual fix arrived the same way. +Neither event produced a commit in any of these repositories, and both were +found only by re-measuring months later. + +## Why this needs a human + +**Dependabot does not maintain these pins.** It advances a SHA-pinned GitHub +Actions ref only when the upstream repository publishes tags — see +`github_actions/lib/dependabot/github_actions/update_checker.rb` in +dependabot-core, where `latest_commit_sha` returns early unless +`latest_version_tag` is present. `PerlToolsTeam/github_workflows` has no +tags, so no update PR is ever opened for these refs. + +The `.github/dependabot.yml` in this repo is still useful — it covers tagged +`actions/*` refs — but it is inert for the pins below. + +## What the pin does and does not freeze + +Frozen: the `PerlToolsTeam/github_workflows` files themselves (the composite +action and the reusable workflows). + +Not frozen: + +- Actions invoked *inside* the pinned upstream files, which use tag refs. + In the composite action: `actions/checkout@v5`, + `shogo82148/actions-setup-perl@v1`, `ilammy/msvc-dev-cmd@v1`, + `actions/upload-artifact@v5`. In the coverage and perlcritic reusable + workflows: `actions/checkout@v7`. Tags can move. +- Container images in the coverage and perlcritic workflows + (`davorg/perl-coveralls:latest`, `davorg/perl-perlcritic`), which float. + +So the pin is a boundary around one upstream repository, not a full CI lock. +It removes the failure mode that actually bit us; it does not make CI +bit-for-bit reproducible. + +## How to review the pin + +Roughly quarterly, or when CI behaves unexpectedly: + + gh api repos/PerlToolsTeam/github_workflows/commits/main \ + --jq '"\(.sha) \(.commit.author.date) \(.commit.message|split("\n")[0])"' + +Compare against the SHA in `ci.yml`. To see what changed since the pin: + + gh api "repos/PerlToolsTeam/github_workflows/commits?sha=main&since=" \ + --jq '.[] | "\(.commit.author.date) \(.sha[0:8]) \(.commit.message|split("\n")[0])"' + +To advance: update all three refs in `ci.yml` plus the trailing +`# main @ ` comments, push to a branch, and let the PR's own CI run be +the verification. Do not advance a pin without a green run — the point of the +pin is that upstream changes arrive as a reviewable event rather than a +surprise. + +Keep the same SHA across all five distributions (PDF-Reuse, PDF-Reuse-Barcode, +PDF-Reuse-OverlayChart, PDF-Reuse-Tutorial, Business-US-USPS-IMB) so a +divergence between them is always a signal rather than noise.