From 81762e4f11ba622c660163055123282efd36d0cd Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Mon, 3 Aug 2026 18:04:36 +0200 Subject: [PATCH] chore: mark action bundles as generated and cover extract-version The four JavaScript actions run from a committed dist/index.js, so every runtime dependency is bundled into it. That puts large generated artifacts in the middle of every review: #79 changed 28 lines of package.json and pnpm-lock.yaml plus 3,176 lines of rebuilt bundle, so 99% of that review was generated output. Marks them as generated in .gitattributes so they collapse in pull request diffs. Reviewers see the source changes, and check_dist:required continues to guarantee that the collapsed output is exactly what that source compiles to, which is what makes collapsing it safe rather than reckless. Adds extract-version to the check_dist matrix. It is a node24 action with an 856K bundle that was not covered, so a stale bundle there went unverified, and it is the action release workflows use to read the version being published. Its committed bundle is currently in sync, so this adds coverage without requiring a rebuild. Documents both in CONTRIBUTING.md, including the part that is easy to miss: a dependency fix without rebuilt bundles does not change what runs, because the lockfile is not consulted when GitHub executes an action. Adds a matching convention to the README, since this repo documents conventions for other repositories too. Co-Authored-By: Claude Opus 5 (1M context) --- .gitattributes | 4 ++++ .github/CONTRIBUTING.md | 12 ++++++++++++ .github/workflows/self-check-dist.yaml | 3 ++- README.md | 12 ++++++++++++ 4 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..33108d0 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,4 @@ +# Action bundles are generated by `pnpm build` and verified by check_dist:required. +# Marking them as generated collapses them in pull request diffs, so reviewers see +# the source changes instead of thousands of lines of bundled output. +actions/*/dist/** linguist-generated=true diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7e40f0b..5d54a06 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -119,3 +119,15 @@ pnpm build ``` The GitHub actions pipeline will attempt to build the actions and check if there are any differences between the built files and those that are committed to the repository. If there are any differences, the pipeline will fail. + +### Why the bundles are committed + +GitHub runs a JavaScript action (`using: node24`) straight from its committed `dist/index.js`. It does not install dependencies or run a build first, so every runtime dependency is bundled into that one file. + +This has a consequence that is easy to miss: updating a bundled dependency in `package.json` and `pnpm-lock.yaml` changes nothing about what actually runs until the bundles are rebuilt. A dependency fix that is not accompanied by rebuilt bundles is not applied. + +The bundles are marked as generated in `.gitattributes`, so they are collapsed in pull request diffs. Review the source changes rather than the bundled output; the `check_dist:required` job is what guarantees the committed bundles are exactly what that source compiles to. + +### When an automated dependency update fails the check + +Automated dependency updates change `package.json` and `pnpm-lock.yaml` but cannot rebuild the bundles, so `check_dist:required` fails on those pull requests. Check the branch out, run `pnpm build`, and commit the rebuilt bundles to it. diff --git a/.github/workflows/self-check-dist.yaml b/.github/workflows/self-check-dist.yaml index 932a495..2b0bcc3 100644 --- a/.github/workflows/self-check-dist.yaml +++ b/.github/workflows/self-check-dist.yaml @@ -14,7 +14,8 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - action_name: ['create-pr', 'assemble-docs', 'submit-docs'] + action_name: + ['create-pr', 'assemble-docs', 'submit-docs', 'extract-version'] steps: - name: Checkout repository uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 diff --git a/README.md b/README.md index 026d435..ad83c11 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,18 @@ Example: name: my_action:required ``` +### Generated files + +A JavaScript action (`using: node24`) is executed by GitHub straight from the committed file its `main` points at, with no install or build step beforehand. Its dependencies therefore have to be committed too, which is why they are bundled into a single `dist/index.js`. + +Mark that output as generated so it collapses in pull request diffs instead of burying the source changes: + +```gitattributes +actions/*/dist/** linguist-generated=true +``` + +Pair it with a job that rebuilds the bundles and fails on any difference. That check is what makes collapsing the diff safe, because it proves the committed output is exactly what the reviewed source compiles to. + ## Locking Versions When referencing 3rd party actions, use a specific commit SHA to lock the version. This ensures that the action will not change unexpectedly, which could lead to breaking changes in your workflows.