Skip to content

Latest commit

 

History

History
314 lines (250 loc) · 21.1 KB

action-distributions.md

File metadata and controls

314 lines (250 loc) · 21.1 KB

GitHub Reusable Workflow: Action distributions

Action distributions

Release License Stars PRs Welcome GitHub Verified Creator

Overview

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.

Configure a repository

  1. Each package needs a lockfile and build and check:dist scripts. Defaults use Node.js 24, npm ci --ignore-scripts, npm run build, and dist/index.js plus dist/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 uses pnpm 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.
  2. Copy the build caller and writer caller. Both call hoverkraft-tech/ci-github-common/.github/workflows/action-distributions.yml pinned to the same reviewed commit. Configure author rules in both callers; package directories are discovered automatically. Repeat other shared settings when overriding defaults.
  3. Set workflow_run.workflows to the build caller's unique, exact name and pull_request.branches to 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.
  4. Provide CI_BOT_APP_CLIENT_ID as a repository variable and CI_BOT_APP_PRIVATE_KEY as 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.
  5. 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.

Choose allowed PR authors

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.

Build and publication behavior

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.

Troubleshooting

  • 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.

Permissions

  • actions: read
  • contents: read
  • pull-requests: read

Usage

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: ""

Inputs

Workflow Call Inputs

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 -

Secrets

Secret Description Required
github-app-key GitHub App private key, passed only by the trusted workflow_run caller. false

Contributing

Contributions are welcome! Please see the contributing guidelines for more details.

License

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.