Skip to content

Add the shared commitlint composite action and switch .github to it #39

Closed

Description

@davison

Goal

Create a composite action in radiusred/.github (suggested path .github/actions/commitlint/action.yml) that runs wagoid/commitlint-github-action pinned to an exact version with the org's commitlint.config.mjs shipped inside the action directory, so callers need no local config. Rewrite .github's own .github/workflows/commitlint.yml as the reference thin caller: pull_request trigger, permissions contents: read and pull-requests: read, actions/checkout with fetch-depth 0, then the action, from a job named exactly "Lint commit messages"; delete the root commitlint.config.mjs. The action must be usable from other repos in the org (uses: radiusred/.github/.github/actions/commitlint@main or a tag; decide and record). Document adoption in CONTRIBUTING.md: the caller file to copy, the permissions private repos need, and that the check context must stay "Lint commit messages" because of the org ruleset. Prove it on this PR's own check. Design decision recorded on radiusred/ops#17.

Requirements

M5-R1,M5-R2

Plan

Requirements covered: M5-R1 (the action, private-repo permissions, CONTRIBUTING) and the .github share of M5-R2 (this repo calls it, no local config, the check passes on this PR).

  1. Composite action at .github/actions/commitlint/ (action.yml, runs.using: composite, no inputs) with commitlint.config.mjs moved into that directory from the repo root. It runs wagoid/commitlint-github-action@v6.2.1 (exact tag) with configFile pointing at that config. Finding that shapes the design: wagoid is a Docker action that resolves configFile as resolve(GITHUB_WORKSPACE, input) inside its container, and the runner's _actions directory (where github.action_path lives) is not mounted into that container, so a path into the action directory would silently fall back to bare config-conventional. The action therefore copies the config from ${{ github.action_path }} to $GITHUB_WORKSPACE/.radiusred-commitlint/commitlint.config.mjs, prints it to the job log (visible proof of which config the lint used), passes that workspace-relative path to wagoid, and removes the copy afterwards (if: always()). The action does not check out; the caller does, with fetch-depth: 0, before the step.
  2. Rewrite .github/workflows/commitlint.yml as the reference caller: pull_request trigger, permissions: contents: read, pull-requests: read, actions/checkout@v4 with fetch-depth: 0, then the action, from a job named exactly Lint commit messages. This repo references the action by local path (./.github/actions/commitlint) so a PR here tests its own version of the action; every other repo uses radiusred/.github/.github/actions/commitlint@main. Delete the root commitlint.config.mjs.
  3. CONTRIBUTING.md: add the action to the inventory; add an adoption section with the exact caller file to copy, the permissions private repos need (contents: read for the checkout, pull-requests: read so the action can list the PR's commits), that the job name must stay exactly Lint commit messages because the org ruleset require-lint pins that check context on every public repo's default branch, and that the action does not check out.
  4. Untouched: reusable-release.yml, reusable-finalize-release.yml, calculate_version.

Tests: the repository has no test framework; the PR's own Lint commit messages check runs through the new action and lints the PR's commits, which is the end-to-end proof M5-R2 asks for. The action's log shows the config it placed and its contents.

Commits (each (#39)): add the action with the config moved into it; switch this repo's workflow to it; document adoption.

Ask-the-human points

None. Whether callers pin @main or a tag is recorded as a Decision comment on this issue rather than raised as a gate: CONTRIBUTING.md already fixes @main for everything this repository exports and the milestone goal is one place to change config and version, which a tag would undo.

Activity

  1. added
    cc:taskCodeCrew: a task issue, attached to its milestone as a sub-issue (SPEC §4)
    on Sep 4, 2026
  2. radiusred-cody commented on Sep 4, 2026

    @radiusred-cody
    Contributor

    Decision: callers reference the action at @main — uses: radiusred/.github/.github/actions/commitlint@main — as CONTRIBUTING.md already prescribes for the reusable release workflows and calculate_version. .github itself calls it by local path (./.github/actions/commitlint) so a PR in this repository exercises the version of the action the PR carries.
    Trade-off: a merge here changes commit linting in every caller at once, so a bad config or a broken wagoid bump lands everywhere in one step; the mitigation is that this repository's own Lint commit messages check runs the action on every PR before it can merge, and a revert is one PR. In exchange the milestone goal holds: the config and the pinned wagoid/commitlint-github-action version change in exactly one place, with no bump PR fanned out to every caller.
    Rejected: tag pinning (@v1, or a SHA). It would make each repo carry the version again, so a config or wagoid change needs a PR per caller — the per-repo drift ops#7 exists to remove. Pinning the inner action stays exact (wagoid/commitlint-github-action@v6.2.1, not the floating @v6), which is where the third-party supply-chain risk sits.

  3. radiusred-cody commented on Sep 4, 2026

    @radiusred-cody
    Contributor

    Started by @radiusred-cody[bot].

  4. radiusred-cody commented on Sep 4, 2026

    @radiusred-cody
    Contributor

    Deviation: the action no longer stages its config at the fixed workspace path .radiusred-commitlint/ named in the plan. It creates a fresh directory with mktemp -d "${GITHUB_WORKSPACE}/.radiusred-commitlint-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}.XXXXXXXX", passes the workspace-relative path to wagoid through a step output, and the if: always() cleanup removes only that directory (guarded on the output being set).
    Why: review finding on PR #40 by radiusred-checky: a fixed path is caller-owned territory, so an adopting repository that already had .radiusred-commitlint/ would have its commitlint.config.mjs overwritten and the whole directory, unrelated files included, deleted by the cleanup. mktemp -d creates a uniquely named directory atomically and fails rather than reuse an existing one, so the action never writes into or deletes anything it did not create. The reason for staging in the workspace at all (wagoid resolves configFile against the workspace inside its container, where the action directory is not mounted) is unchanged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    cc:taskCodeCrew: a task issue, attached to its milestone as a sub-issue (SPEC §4)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions