Rebuild committed Node.js bundles in the same dependency PR through one reusable workflow with separate build and writer event callers. Configure workflow inputs; no repository configuration file is needed. The dedicated action owns the implementation and tests. Existing CI must check bundle consistency before merging.
- Each package needs a lockfile and build and check:dist scripts. Defaults use Node.js 24,
npm ci --ignore-scripts,npm run build, anddist/index.jsplusdist/licenses.txt. For pnpm workspaces, select the root working directory, commit pnpm-lock.yaml and pin packageManager in the root package.json. Shared ci-github-nodejs actions detect and configure the package manager from the first affected package. Installation usespnpm install --frozen-lockfile. Set ignore-scripts to false when approved hooks are required; pnpm's allowBuilds policy still applies. Only the read-only builder installs dependencies or executes repository scripts. All selected packages must use the same package manager. The shared setup configures tooling only; the builder installs once per affected package using the shared detected command. The node-version input is applied after setup to preserve the requested runtime. - Copy the build caller and
writer caller. Both call
hoverkraft-tech/ci-github-common/.github/workflows/action-distributions.ymlpinned to the same reviewed commit. Configure author rules in both callers; package directories are discovered automatically. Repeat other shared settings when overriding defaults. - Set
workflow_run.workflowsto the build caller's unique, exactnameandpull_request.branchesto the default branch. GitHub rejects a workflow listening to its own completion, so the two small event callers are required even though they share one reusable workflow. - Provide
CI_BOT_APP_CLIENT_IDas a repository variable andCI_BOT_APP_PRIVATE_KEYas an Actions secret. Install the App with contents write, actions read and pull requests read on the consumer repository. Only the writer caller passes the App key; the build caller passes no secrets. - Merge the callers into the default branch. Trigger a fresh dependency update to verify regeneration, CI on the generated commit and bot rebasing. GitHub.com is required for self-repository action references.
The generated Usage block lists inputs. Actual execution requires both events in
the linked callers; a push-only caller does not run either job. To customize the
build, set build-script to a package script name and choose node-version. Override
output-directory, required-files, artifact-name, retention-days or
commit-message when needed. A workspace build can emit several bundles: supply
newline-separated output-directory paths or patterns such as actions/**/dist
relative to the workspace root. Patterns support *, ** and ?. Both jobs
resolve them against committed directories in the trusted PR base revision,
never the PR checkout or artifact. New matching directories become eligible
after reaching the default branch. Hidden and node_modules directories are excluded.
Every pattern must match; duplicate or overlapping resolved directories fail.
Required files must exist in every resolved output directory. Keep the patterns
and max-artifact-size limit identical in both callers.
By default, discover root and actions/** packages declaring the selected build
script and check:dist. Override working-directories with newline-separated
literal directories or glob patterns (*, **, ?). Literal directories explicitly
define the allowlist; glob matches must declare both scripts. No matches is a
successful no-op. Dependency, generated and hidden directories are excluded.
Selected directories must not overlap or contain traversal components.
Build and writer discovery read manifests from the PR's default-branch base revision through GitHub's API. No repository code is executed during discovery. A newly introduced package must reach the default branch before automated rebuilds can write its output; normal distribution CI tests it on the PR. An empty required-files accepts any nonempty output for each affected package. The writer uses its own default-branch inputs and manifests as the allowlist. A PR cannot expand its write scope by editing inputs or package manifests.
pull-request-authors is a JSON array. It defaults to ["dependabot","renovate"],
which selects GitHub Dependabot and the hosted Renovate App. Both presets check
the PR creator and event actor by login and numeric account ID, with the respective
dependabot/ and renovate/ branch prefixes. Other PRs are skipped before any
package code executes.
For self-hosted Renovate or another automation account, pass an explicit rule in both callers. For example, the Hoverkraft callers add their own App:
pull-request-authors: |
["dependabot", "renovate", {"login":"hoverkraft-bot[bot]","id":128996893,"branch-prefix":"renovate/"}]Verify an account's ID with gh api 'users/ACCOUNT_LOGIN' --jq .id. Custom rules
require login and numeric id; branch-prefix and commit-message-suffix are
optional. Authorizing a branch prefix alone is insufficient. Inputs do not enable
or extend a dependency updater's package-manager coverage.
Dependabot's preset adds [dependabot skip] to generated commits so it can rebase
over them. For Renovate, add the writer's actual commit author email to
gitIgnoredAuthors
in its existing configuration; otherwise Renovate can treat the generated commit
as a manual modification and stop updating that PR. The common and container
repositories configure 128996893+hoverkraft-bot[bot]@users.noreply.github.com.
Other installations must use their own writer's email.
Every generated commit includes a fixed body trailer. The helper skips that head on subsequent events, including when Renovate and the writer use the same App. Normal CI still runs; no CI skip marker or automatic merge is configured.
The builder checks out the exact PR head and rebuilds affected configured packages, including grouped updates and lockfile-only changes. Generated files and licenses are uploaded together. Updated dependencies execute only in this read-only job.
The writer checks the originating run and current PR through GitHub's API. It accepts only the current successful attempt, the resolved builder and configured author, a same-repository branch, and an unchanged open PR targeting the default branch. It treats the artifact as bytes, validates every path, and commits only changes inside the selected output directories. Deleted chunks are removed; unrelated files remain untouched. It never checks out or executes PR code. These origin and head checks cannot be disabled through inputs.
The writer resolves its caller file through GitHub, then reads the workflow definitions at its default-branch revision. Its workflow_run.workflows filter must contain one exact name matching one pull_request workflow in that snapshot. Missing or duplicate names, multiple names and wildcard filters fail publication. The originating run must belong to that workflow path; a name supplied by a PR or the run is never used to authorize publication. No builder-path input is needed.
One generated commit covers all affected packages. The App token triggers normal CI. Identical output and superseded runs produce no commit. Publication is serialized per branch and checks the expected head atomically. A concurrent update fails publication without a force push.
- A failed build leaves the PR unchanged. Fix its package build; existing distribution checks continue to prevent stale merges.
- Missing or expired artifacts fail publication. Retention defaults to one day; rerun the builder to produce a new attempt, then inspect the writer run.
- A moved or closed PR is skipped. A new bot update rebuilds the latest head; a failed atomic write never replaces newer commits.
- Token creation or commit failures require checking the App installation, permissions, repository rules and Actions secret. No PAT fallback is used.
- Artifacts default to a 20 MiB JSON limit; max-artifact-size can raise it to 128 MiB. Keep output below 1,000 regular files and each file below 50 MiB. Symbolic links, executable distribution files and truncated GitHub tree/file listings are rejected.
- Changes above 20 MiB use individual Git blob uploads and one Git commit, followed by a non-forced atomic update guarded by the expected head. Unlike the small-change commit API, this path does not automatically sign the commit. Repositories requiring signed bot commits must account for this before enabling large artifacts.
See ADR 0002 for the design, alternatives and rollout constraints.
actions:readcontents:readpull-requests:read
name: Action distributions
on:
push:
branches:
- main
permissions: {}
jobs:
action-distributions:
uses: hoverkraft-tech/ci-github-common/.github/workflows/action-distributions.yml@d606f77fad305ef07dfde3db5270f5e324019c97 # 4.2.4
permissions:
actions: read
contents: read
pull-requests: read
secrets:
# GitHub App private key, passed only by the trusted workflow_run caller.
github-app-key: ""
with:
# Newline-separated package directories or glob patterns (`*`, `**`, `?`). Empty discovers root and `actions/**` packages declaring build and check:dist scripts.
working-directories: ""
# Newline-separated generated directories or glob patterns (`*`, `**`, `?`) relative to each package. Patterns select committed directories from the trusted base revision; matches must be non-overlapping.
# Default: `dist`
output-directory: dist
# Newline-separated files required in every generated directory. Empty accepts any nonempty output.
# Default: `index.js
# licenses.txt
# `
required-files: |
index.js
licenses.txt
# JSON array of dependabot or renovate presets, or objects with login, numeric account ID and optional branch-prefix and commit-message-suffix.
# Default: `["dependabot","renovate"]`
pull-request-authors: '["dependabot","renovate"]'
# Artifact name prefix shared by build and commit. The run attempt is appended automatically.
# Default: `action-distributions`
artifact-name: action-distributions
# Node.js version used for dependency installation and the build script.
# Default: `24`
node-version: "24"
# Package script name to run after a locked dependency installation.
# Default: `build`
build-script: build
# Disable install lifecycle scripts. Set false only when the read-only builder needs approved hooks.
# Default: `true`
ignore-scripts: true
# Maximum serialized artifact size in MiB (integer from 1 to 128). Use the same limit for build and writer.
# Default: `20`
max-artifact-size: 20
# Artifact retention in days, within the repository's artifact policy.
# Default: `1`
retention-days: 1
# Single-line commit headline. Per-author suffixes and a loop-prevention body trailer are appended.
# Default: `build: regenerate action distributions`
commit-message: "build: regenerate action distributions"
# Client ID of the GitHub App installed on the caller repository with contents write and actions and pull requests read access.
github-app-client-id: ""| Input | Description | Required | Type | Default |
|---|---|---|---|---|
working-directories |
Newline-separated package directories or glob patterns (*, **, ?). Empty discovers root and actions/** packages declaring build and check:dist scripts. |
false | string | - |
output-directory |
Newline-separated generated directories or glob patterns (*, **, ?) relative to each package. Patterns select committed directories from the trusted base revision; matches must be non-overlapping. |
false | string | dist |
required-files |
Newline-separated files required in every generated directory. Empty accepts any nonempty output. | false | string | index.js
licenses.txt |
pull-request-authors |
JSON array of dependabot or renovate presets, or objects with login, numeric account ID and optional branch-prefix and commit-message-suffix. | false | string | ["dependabot","renovate"] |
artifact-name |
Artifact name prefix shared by build and commit. The run attempt is appended automatically. | false | string | action-distributions |
node-version |
Node.js version used for dependency installation and the build script. | false | string | 24 |
build-script |
Package script name to run after a locked dependency installation. | false | string | build |
ignore-scripts |
Disable install lifecycle scripts. Set false only when the read-only builder needs approved hooks. | false | boolean | true |
max-artifact-size |
Maximum serialized artifact size in MiB (integer from 1 to 128). Use the same limit for build and writer. | false | number | 20 |
retention-days |
Artifact retention in days, within the repository's artifact policy. | false | number | 1 |
commit-message |
Single-line commit headline. Per-author suffixes and a loop-prevention body trailer are appended. | false | string | build: regenerate action distributions |
github-app-client-id |
Client ID of the GitHub App installed on the caller repository with contents write and actions and pull requests read access. | false | string | - |
| Secret | Description | Required |
|---|---|---|
github-app-key |
GitHub App private key, passed only by the trusted workflow_run caller. | false |
Contributions are welcome! Please see the contributing guidelines for more details.
This project is licensed under the MIT License.
SPDX-License-Identifier: MIT
Copyright © 2026 hoverkraft-tech
For more details, see the license.
This documentation was automatically generated by CI Dokumentor.