From fd6610baad4ad9420731204e41ea6c726970ea80 Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Tue, 10 Nov 2026 22:43:52 +0100 Subject: [PATCH 1/7] feat(label-dispatch): start the workflow of a label by workflow_dispatch (#149) A label no longer creates a run of every heavy workflow of a package: label-dispatch.yml dispatches only the workflow of the label just added, so the runs of different labels accumulate on the pull request and none cancels another. - label-dispatch.yml (reusable) and scripts/label-dispatch/{plan,test}.sh: the mapping label -> workflow, tested by label-dispatch-tests.yml - ci, documentation, breakage-suite, breakage: a workflow_dispatch with the input `pr` counts as a run of that pull request (concurrency group, baseline, comment, preview) - docs/workflows/label-dispatch.md, labels.md, superseded-runs.md, README.md Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/breakage-suite.yml | 32 +++-- .github/workflows/breakage.yml | 10 +- .github/workflows/ci.yml | 6 +- .github/workflows/documentation.yml | 24 ++-- .github/workflows/label-dispatch-tests.yml | 26 ++++ .github/workflows/label-dispatch.yml | 82 +++++++++++++ docs/README.md | 2 + docs/conventions/labels.md | 8 ++ docs/workflows/label-dispatch.md | 136 +++++++++++++++++++++ docs/workflows/superseded-runs.md | 8 ++ scripts/label-dispatch/plan.sh | 48 ++++++++ scripts/label-dispatch/test.sh | 40 ++++++ 12 files changed, 403 insertions(+), 19 deletions(-) create mode 100644 .github/workflows/label-dispatch-tests.yml create mode 100644 .github/workflows/label-dispatch.yml create mode 100644 docs/workflows/label-dispatch.md create mode 100755 scripts/label-dispatch/plan.sh create mode 100755 scripts/label-dispatch/test.sh diff --git a/.github/workflows/breakage-suite.yml b/.github/workflows/breakage-suite.yml index 5ed01e7..42dde50 100644 --- a/.github/workflows/breakage-suite.yml +++ b/.github/workflows/breakage-suite.yml @@ -62,9 +62,11 @@ on: # skipped, and a `concurrency` of the caller would still cancel the run in progress. The # group starts with a name of its own: it must differ from every group of a caller. # `group` keeps apart the suites called by one caller workflow. +# A run started by label-dispatch.yml (a `workflow_dispatch` with the input `pr`) is a +# run of that pull request: same group, same cancellation. concurrency: - group: ctactions-breakage-suite-${{ github.workflow }}-${{ inputs.group }}-${{ github.event.pull_request.number || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + group: ctactions-breakage-suite-${{ github.workflow }}-${{ inputs.group }}-${{ github.event.pull_request.number || github.event.inputs.pr || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '') }} jobs: # Whether the suite runs (docs/workflows/guard.md): no on a pull request that is not open; @@ -273,12 +275,27 @@ jobs: pattern: breakage-cell-${{ inputs.group }}-* merge-multiple: true + # The pull request of this run: the event's on a `pull_request`, the input `pr` on a + # dispatch from label-dispatch.yml, none on a push, a manual run or the cron. + - name: Pull request + id: pr + env: + GH_TOKEN: ${{ github.token }} + NUMBER: ${{ github.event.pull_request.number || github.event.inputs.pr }} + run: | + [ -n "$NUMBER" ] || exit 0 + { + echo "number=$NUMBER" + gh api "repos/$GITHUB_REPOSITORY/pulls/$NUMBER" \ + --jq '"base_sha=\(.base.sha)", "fork=\(.head.repo.fork // false)"' + } >> "$GITHUB_OUTPUT" + # On a PR: the run of this workflow on the base commit, outside a PR (push or dispatch) - name: Baseline - if: github.event_name == 'pull_request' + if: steps.pr.outputs.number != '' env: GH_TOKEN: ${{ github.token }} - BASE_SHA: ${{ github.event.pull_request.base.sha }} + BASE_SHA: ${{ steps.pr.outputs.base_sha }} WORKFLOW_REF: ${{ github.workflow_ref }} GROUP: ${{ inputs.group }} run: | @@ -297,7 +314,7 @@ jobs: TARGETS: ${{ needs.plan.outputs.targets }} VERSIONS: ${{ inputs.versions }} GROUP: ${{ inputs.group }} - BASE_SHA: ${{ github.event.pull_request.base.sha }} + BASE_SHA: ${{ steps.pr.outputs.base_sha }} SHA: ${{ github.event.pull_request.head.sha || github.sha }} run: | expected=$(( $(jq length <<< "$TARGETS") * $(jq length <<< "$VERSIONS") )) @@ -322,14 +339,15 @@ jobs: # Not on a pull request from a fork: its token is read-only and the comment would # fail the job (and hide the verdict below). The report is in the run's summary. - name: Comment on the PR - if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork != true + if: steps.pr.outputs.number != '' && steps.pr.outputs.fork != 'true' uses: actions/github-script@v9 env: MARKER: + PR: ${{ steps.pr.outputs.number }} with: script: | const body = require('fs').readFileSync('out/summary.md', 'utf8') - const issue_number = context.payload.pull_request.number + const issue_number = Number(process.env.PR) const comments = await github.paginate(github.rest.issues.listComments, { owner: context.repo.owner, repo: context.repo.repo, issue_number }) const mine = comments.find(c => c.body && c.body.startsWith(process.env.MARKER)) diff --git a/.github/workflows/breakage.yml b/.github/workflows/breakage.yml index e563880..caf74b7 100644 --- a/.github/workflows/breakage.yml +++ b/.github/workflows/breakage.yml @@ -31,9 +31,11 @@ on: # skipped, and a `concurrency` of the caller would still cancel the run in progress. The # group starts with a name of its own: it must differ from every group of a caller. # The inputs keep apart the packages called by one caller workflow. +# A run started by label-dispatch.yml (a `workflow_dispatch` with the input `pr`) is a +# run of that pull request: same group, same cancellation. concurrency: - group: ctactions-breakage-${{ github.workflow }}-${{ inputs.pkgname }}-${{ inputs.pkgpath }}-${{ inputs.pkgbreak }}-${{ inputs.pkgversion }}-${{ github.event.pull_request.number || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + group: ctactions-breakage-${{ github.workflow }}-${{ inputs.pkgname }}-${{ inputs.pkgpath }}-${{ inputs.pkgbreak }}-${{ inputs.pkgversion }}-${{ github.event.pull_request.number || github.event.inputs.pr || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '') }} jobs: break: @@ -217,12 +219,14 @@ jobs: - name: Comment on PR if: github.event.pull_request.head.repo.fork != true uses: actions/github-script@v9 + env: + PR: ${{ github.event.pull_request.number || github.event.inputs.pr }} with: github-token: ${{ secrets.GITHUB_TOKEN }} script: | const fs = require('fs') const msg = fs.readFileSync('breakage/summary.md', 'utf8') - const prNumber = context.payload.pull_request?.number + const prNumber = Number(process.env.PR) if (!prNumber) { console.log("No PR number found.") return diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9e44cc7..3828c6a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -75,9 +75,11 @@ on: # group starts with a name of its own: it must differ from every group of a caller. # `runner_type` and `runs_on` keep apart the calls of one caller workflow (the GitHub, kkt # and occidata runners of one `CI.yml`, which also reach this workflow through ci-gpu.yml). +# A run started by label-dispatch.yml (a `workflow_dispatch` with the input `pr`) is a +# run of that pull request: same group, same cancellation. concurrency: - group: ctactions-ci-${{ github.workflow }}-${{ inputs.runner_type }}-${{ inputs.runs_on }}-${{ github.event.pull_request.number || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + group: ctactions-ci-${{ github.workflow }}-${{ inputs.runner_type }}-${{ inputs.runs_on }}-${{ github.event.pull_request.number || github.event.inputs.pr || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '') }} jobs: # Whether the jobs below run (docs/workflows/guard.md): no on a pull request that is not diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 5d3b474..ea5da19 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -51,9 +51,11 @@ on: # not in the caller: a label that changes nothing creates a run whose calling job is # skipped, and a `concurrency` of the caller would still cancel the run in progress. The # group starts with a name of its own: it must differ from every group of a caller. +# A run started by label-dispatch.yml (a `workflow_dispatch` with the input `pr`) is a +# run of that pull request: same group, same cancellation. concurrency: - group: ctactions-documentation-${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + group: ctactions-documentation-${{ github.workflow }}-${{ github.event.pull_request.number || github.event.inputs.pr || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '') }} jobs: # Whether the jobs below run (docs/workflows/guard.md): no on a pull request that is not @@ -118,15 +120,23 @@ jobs: # PR previews are opt-in: `DOCUMENTER_PUSH_PREVIEW` is "true" only on a PR carrying # the `documentation push preview` label, "false" otherwise. A caller's make.jl reads # it as `push_preview = get(ENV, "DOCUMENTER_PUSH_PREVIEW", "false") == "true"`. - # Inside a reusable workflow `github.event` is the caller's event, so the PR's labels - # are visible here. A make.jl that still hardcodes `push_preview` ignores it. + # Inside a reusable workflow `github.event` is the caller's event: the PR's labels + # are visible here on a `pull_request`, and on a `workflow_dispatch` from + # label-dispatch.yml the inputs `pr` and `preview` say the same. A make.jl that + # still hardcodes `push_preview` ignores it. + # Documenter takes a build for a preview only on `GITHUB_EVENT_NAME=pull_request` and + # `GITHUB_REF=refs/pull//merge`; a dispatched run has neither, so the build is told. - name: Build and deploy env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} - DOCUMENTER_PUSH_PREVIEW: ${{ github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'documentation push preview') }} + DOCUMENTER_PUSH_PREVIEW: ${{ (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'documentation push preview')) || (github.event_name == 'workflow_dispatch' && github.event.inputs.pr != '' && github.event.inputs.preview == 'true') }} + DISPATCH_PR: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.pr || '' }} GKSwstype: 100 run: | + if [ -n "$DISPATCH_PR" ]; then + export GITHUB_EVENT_NAME=pull_request GITHUB_REF="refs/pull/$DISPATCH_PR/merge" + fi julia --project=docs/ -e 'ENV["GKSwstype"]="nul"; include("docs/make.jl")' echo "📂 Listing docs/build/assets:" ls -R docs/build/assets || true @@ -145,7 +155,7 @@ jobs: # `build` ran. if: > !cancelled() && needs.build.result == 'success' && - inputs.gpu_runner == 'auto' && github.event_name != 'pull_request' + inputs.gpu_runner == 'auto' && github.event_name != 'pull_request' && !github.event.inputs.pr uses: control-toolbox/CTActions/.github/workflows/select-gpu-runner.yml@main secrets: CT_RUNNERS_CLIENT_ID: ${{ secrets.CT_RUNNERS_CLIENT_ID }} @@ -157,7 +167,7 @@ jobs: needs: [build, select-gpu] if: > always() && needs.build.result == 'success' && - inputs.gpu_runner != '' && github.event_name != 'pull_request' && + inputs.gpu_runner != '' && github.event_name != 'pull_request' && !github.event.inputs.pr && (inputs.gpu_runner != 'auto' || needs.select-gpu.result == 'success') runs-on: ${{ fromJSON(inputs.gpu_runner == 'auto' && needs.select-gpu.outputs.runs_on_labels || inputs.gpu_runner) }} timeout-minutes: ${{ inputs.gpu_timeout_minutes }} diff --git a/.github/workflows/label-dispatch-tests.yml b/.github/workflows/label-dispatch-tests.yml new file mode 100644 index 0000000..12b6821 --- /dev/null +++ b/.github/workflows/label-dispatch-tests.yml @@ -0,0 +1,26 @@ +name: Label dispatch tests + +# Self-test of label-dispatch.yml (docs/workflows/label-dispatch.md): the tests of its +# mapping label -> workflow (scripts/label-dispatch/test.sh). + +on: + pull_request: + paths: + - '.github/workflows/label-dispatch.yml' + - '.github/workflows/label-dispatch-tests.yml' + - 'scripts/label-dispatch/**' + push: + branches: [main] + paths: + - '.github/workflows/label-dispatch.yml' + - '.github/workflows/label-dispatch-tests.yml' + - 'scripts/label-dispatch/**' + workflow_dispatch: + +jobs: + test: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@v7 + - run: bash scripts/label-dispatch/test.sh diff --git a/.github/workflows/label-dispatch.yml b/.github/workflows/label-dispatch.yml new file mode 100644 index 0000000..a598064 --- /dev/null +++ b/.github/workflows/label-dispatch.yml @@ -0,0 +1,82 @@ +name: Label dispatch + +# Starts, for a label added to a pull request, the workflow of that label, and only that +# one (docs/workflows/label-dispatch.md). The heavy workflows of a package (CI, +# Documentation, Breakage) do not listen to `pull_request`: a label is not a filter of that +# event, so every label would create a run of each of them, and the latest run, all jobs +# skipped, would hide on the pull request page the one still running. They listen to +# `workflow_dispatch`, and this workflow dispatches them: +# +# - `labeled`: the workflow of the label just added; a label that starts nothing, nothing; +# - `synchronize`, `reopened`: the workflow of every label the pull request carries. +# +# A run started by a label is never cancelled by another label. A new push cancels the run +# of the same workflow and the same pull request (docs/workflows/superseded-runs.md). +# The mapping label -> workflow is scripts/label-dispatch/plan.sh. Each dispatched workflow +# declares the inputs it is given: `pr` always, `target` (CI, Breakage), `preview` +# (Documentation). +# +# Not for a pull request that is not open, nor for one from a fork: a fork's branch cannot +# be dispatched and its token is read-only. The job says so in its summary. + +on: + workflow_call: + inputs: + ctactions_ref: + description: 'Ref of CTActions whose script is used (main; a branch to test a change)' + required: false + type: string + default: main + +jobs: + dispatch: + runs-on: ubuntu-latest + timeout-minutes: 5 + permissions: + contents: read + actions: write # gh workflow run + env: + DISPATCHABLE: ${{ github.event.pull_request.state == 'open' && github.event.pull_request.head.repo.full_name == github.repository }} + steps: + - name: Not dispatched + if: env.DISPATCHABLE != 'true' + run: | + echo "Not dispatched, the pull request is not open or its branch is in a fork." >> "$GITHUB_STEP_SUMMARY" + + - uses: actions/checkout@v7 + if: env.DISPATCHABLE == 'true' + with: + repository: control-toolbox/CTActions + ref: ${{ inputs.ctactions_ref }} + path: .ctactions + sparse-checkout: scripts/label-dispatch + + - name: Dispatch + if: env.DISPATCHABLE == 'true' + env: + GH_TOKEN: ${{ github.token }} + ACTION: ${{ github.event.action }} + LABEL: ${{ github.event.label.name }} + LABELS: ${{ toJSON(github.event.pull_request.labels.*.name) }} + PR: ${{ github.event.pull_request.number }} + REF: ${{ github.event.pull_request.head.ref }} + run: | + plan=$(bash .ctactions/scripts/label-dispatch/plan.sh) + if [ -z "$plan" ]; then + echo "Nothing to dispatch for \`$ACTION\` ${LABEL:+(label \`$LABEL\`)}." >> "$GITHUB_STEP_SUMMARY" + exit 0 + fi + status=0 + echo "Dispatched on \`$REF\` for #$PR:" >> "$GITHUB_STEP_SUMMARY" + while read -r file args; do + flags=(-f "pr=$PR") + for kv in $args; do flags+=(-f "$kv"); done + if gh workflow run "$file" --ref "$REF" "${flags[@]}"; then + echo "- \`$file\` $args" >> "$GITHUB_STEP_SUMMARY" + else + echo "::error::could not dispatch $file: does it have a workflow_dispatch trigger with the inputs pr and the ones of the label?" + echo "- ❌ \`$file\` $args" >> "$GITHUB_STEP_SUMMARY" + status=1 + fi + done <<< "$plan" + exit $status diff --git a/docs/README.md b/docs/README.md index d28b392..451d28b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -73,6 +73,7 @@ token. | --- | --- | --- | --- | | [`ci.yml`](workflows/ci.md) | `CI.yml` | Test suite over a Julia × OS × arch matrix, on GitHub-hosted or self-hosted (GPU) runners | label `run ci ` | | [`ci-gpu.yml`](workflows/ci-gpu.md) | `CI.yml` | `ci.yml` on `kkt`, or `occidata` if `kkt` is offline; pushes to `main` and tags | push | +| [`label-dispatch.yml`](workflows/label-dispatch.md) | `Labels.yml` | Starts the workflow of the label just added (`workflow_dispatch`), so that the runs of different labels accumulate on the pull request | every pull request | | [Superseded runs](workflows/superseded-runs.md) | `ci.yml`, `documentation.yml`, `breakage-suite.yml`, `breakage.yml` | On a pull request, a new run cancels the previous one of the same workflow; nothing is cancelled on `main` or tags | declared in the four, nothing to add in a package | | [`guard.yml`](workflows/guard.md) | `ci.yml`, `coverage.yml`, `breakage-suite.yml`, `documentation.yml` | Whether the jobs below run: no on a pull request that is not open; on `main`, the label `ci on main: changes only` | called by the four above | | [`select-gpu-runner.yml`](workflows/select-gpu-runner.md) | `ci-gpu.yml`, `documentation.yml` | Picks `kkt` unless offline, else `occidata` | called by the two above | @@ -98,6 +99,7 @@ token. | [`compat-prune-tests.yml`](workflows/compat-prune.md#tests) | Self-test of the prune: its test suite, then a real dry-run audit | PR or push touching it, by hand | | [`release-tests.yml`](workflows/release-gate.md#tests) | Self-test of the release tool (`scripts/release`) on Julia 1.10, 1.12, 1.13 | PR or push touching it, by hand | | [`guard-tests.yml`](workflows/guard.md#testing-a-change) | Self-test of `guard.yml`: `run` follows the state of the pull request | PR touching it, by hand | +| [`label-dispatch-tests.yml`](workflows/label-dispatch.md#testing-a-change) | Self-test of the mapping label → workflow of `label-dispatch.yml` | PR or push touching it, by hand | | [`ci-main-tests.yml`](workflows/ci-on-main.md#testing-a-change-to-this-mechanism) | Self-test of the changes-only decision (`scripts/ci-main`) | PR or push touching it, by hand | | [`breakage-tests.yml`](workflows/breakage-suite.md#tests) | Self-test of the breakage report (`scripts/breakage`) | PR or push touching it, by hand | | `lint-workflows.yml` | actionlint on every workflow (expressions, inputs and secrets of reusable workflows, runner labels from `.github/actionlint.yaml`, shellcheck on `run:` scripts) | PR or push touching `.github/`, by hand | diff --git a/docs/conventions/labels.md b/docs/conventions/labels.md index 0cff7ff..0330910 100644 --- a/docs/conventions/labels.md +++ b/docs/conventions/labels.md @@ -9,6 +9,14 @@ and always run on `push` to `main` and on tags, so that `main` stays green. ## The guard +> **Superseded for the heavy workflows.** `CI.yml`, `Documentation.yml` and `Breakage.yml` +> no longer listen to `pull_request`: a label dispatches them through +> [`label-dispatch.yml`](../workflows/label-dispatch.md), one run per label, and they guard +> their jobs on the dispatch inputs, not on the labels. What follows (the `if:` guard, the +> `types:` list) applies to a workflow that still listens to `pull_request`. The vocabulary +> below is unchanged, and the mapping is in `scripts/label-dispatch/plan.sh`. + + The caller guards its job with: ```yaml diff --git a/docs/workflows/label-dispatch.md b/docs/workflows/label-dispatch.md new file mode 100644 index 0000000..bb790f7 --- /dev/null +++ b/docs/workflows/label-dispatch.md @@ -0,0 +1,136 @@ +# label-dispatch.yml + +[← Workflows of control-toolbox](../README.md) + +Starts, for a label added to a pull request, the workflow of that label, and only that +one. Caller: `Labels.yml`, the same in every package. + +## Why + +The heavy workflows (`CI.yml`, `Documentation.yml`, `Breakage.yml`) used to listen to +`pull_request: labeled`. A label is not a filter of that event: **every label created a +run of each of them**, with the `if:` of the caller skipping the jobs. The guards +(see [Labels](../conventions/labels.md)) kept the run in progress alive, but the new run of +the same workflow, all jobs skipped, was the one the pull request page showed. The CI still +running was hidden behind it, and each label left about thirty skipped jobs in the Checks. + +Now the heavy workflows do not listen to `pull_request`. They listen to +`workflow_dispatch`, and `label-dispatch.yml` dispatches them, one run per label: +runs started by different labels **accumulate** on the pull request, side by side. + +Nothing is cancelled when a label is added: a run is cancelled only by a newer run of the +same workflow, the same target and the same pull request +([Superseded runs](superseded-runs.md)). + +## What it dispatches + +| Event | Dispatched | +| --- | --- | +| `labeled` | the workflow of the label just added; nothing for a label that starts nothing (`bug`) | +| `synchronize`, `reopened` | the workflow of **every** label the pull request carries | + +| Label | Workflow | Inputs | +| --- | --- | --- | +| `run ci github-runner` | `CI.yml` | `target=github` | +| `run ci occidata-runner` | `CI.yml` | `target=occidata` | +| `run ci kkt-runner` | `CI.yml` | `target=kkt` | +| `run breakage` | `Breakage.yml` | `target=packages` | +| `run breakage applications` | `Breakage.yml` | `target=applications` | +| `run documentation` | `Documentation.yml` | `preview=true` or `false` | +| `documentation push preview` | modifier, see below | | + +The mapping is in [`scripts/label-dispatch/plan.sh`](../../scripts/label-dispatch/plan.sh), +with its tests. Every dispatch also passes `pr`, the number of the pull request. + +`documentation push preview` starts nothing alone. Added after `run documentation`, it +dispatches the documentation again, with `preview=true`. + +Not dispatched: a pull request that is not open, and a pull request from a fork (its +branch cannot be dispatched, and its token is read-only). The job's summary says so. +`unlabeled` is not subscribed: removing a label does not cancel a run. + +## In a package + +```yaml +# .github/workflows/Labels.yml +name: Labels + +on: + pull_request: + types: [labeled, synchronize, reopened] + +jobs: + call: + permissions: + contents: read + actions: write + uses: control-toolbox/CTActions/.github/workflows/label-dispatch.yml@main +``` + +```yaml +# .github/workflows/CI.yml: the other callers follow the same pattern +name: CI +run-name: CI ${{ inputs.target }}${{ inputs.pr && format(' #{0}', inputs.pr) || '' }} + +on: + push: + branches: [main] + tags: '*' + workflow_dispatch: + inputs: + pr: + description: 'Pull request number, set by label-dispatch.yml' + required: false + default: '' + target: + description: 'github, occidata or kkt' + required: false + default: '' + +jobs: + test-cpu-github: + if: github.event_name == 'push' || inputs.target == 'github' + uses: control-toolbox/CTActions/.github/workflows/ci.yml@main + with: { ... } +``` + +A dispatched workflow **declares every input it is given** (`pr`; `target` for CI and +Breakage; `preview` for Documentation), or the dispatch fails with `Unexpected inputs`. +A `workflow_dispatch` by hand has no `pr`: for the breakage suite it is the run that +becomes the baseline of the next release PR, as before. + +## What the reusable workflows do with `pr` + +Inside a reusable workflow `github.event` is the caller's event, so `github.event.inputs.pr` +is readable without passing it through every caller. + +- `ci.yml`, `documentation.yml`, `breakage-suite.yml`, `breakage.yml`: the concurrency + group ends with the pull request number, and a run with `pr` is cancelled by a newer one + of the same group. +- `breakage-suite.yml`: the base commit, the baseline and the comment come from the pull + request read through the API. +- `documentation.yml`: `preview=true` sets `DOCUMENTER_PUSH_PREVIEW`, and the build runs + with `GITHUB_EVENT_NAME=pull_request` and `GITHUB_REF=refs/pull//merge`, which is + what Documenter needs to deploy `previews/PR`. The GPU pass is skipped, as on any + pull request. + +## What changes in the run + +- A dispatched run checks out the **head of the branch**, not the merge commit of the pull + request (`refs/pull//merge`) that a `pull_request` run tests. +- The run belongs to the head commit, so it is in the pull request's checks, with the + names of the callers' jobs. A branch protection that requires a check by name must be + checked once a package has moved. +- A run is named by `run-name`, for example `CI kkt #42`. + +## Testing a change + +`label-dispatch-tests.yml` runs the tests of the mapping. The dispatch itself is tested on +a pull request of a package whose `Labels.yml` points to the branch of CTActions +(`label-dispatch.yml@`, with `ctactions_ref: `): + +1. A label: one run, the one of the label, and a `Labels` run of a few seconds. +2. A second label while the first run goes on: both run, nothing is cancelled. +3. A push: each labelled workflow restarts once, the previous run is cancelled. +4. `bug`: nothing is dispatched. +5. `documentation push preview` after `run documentation`: the preview is deployed. diff --git a/docs/workflows/superseded-runs.md b/docs/workflows/superseded-runs.md index 5df6a3b..3216b02 100644 --- a/docs/workflows/superseded-runs.md +++ b/docs/workflows/superseded-runs.md @@ -40,6 +40,14 @@ concurrency: - **The prefix `ctactions-…`** differs from every group of a caller. A caller and a callee in the same group wait for each other for ever. +## Runs started by a label + +A run started by [`label-dispatch.yml`](label-dispatch.md) is a `workflow_dispatch` with +the input `pr`. For these four workflows it counts as a run of that pull request: the +group ends with `github.event.inputs.pr`, and `cancel-in-progress` is on. A push cancels +the run of each labelled workflow, a label never cancels the run of another one: their +groups differ by workflow and, in `ci.yml`, by runner. + ## Why not in the callers The package workflows run on label events (`labeled`, `unlabeled`) and guard their calling diff --git a/scripts/label-dispatch/plan.sh b/scripts/label-dispatch/plan.sh new file mode 100755 index 0000000..6473343 --- /dev/null +++ b/scripts/label-dispatch/plan.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +# What label-dispatch.yml starts (docs/workflows/label-dispatch.md): one line per run, +# ` =...`, on the standard output. +# +# Environment: +# ACTION the pull request event: labeled, synchronize, reopened +# LABEL the label that was just added (event `labeled`) +# LABELS JSON array of the labels the pull request carries +# +# The table is the one of docs/conventions/labels.md. On `labeled`, only the added label +# counts: the runs that other labels started are left alone. On any other event, every +# label of the pull request counts: a push or a reopening restarts them all. +# `documentation push preview` is a modifier: it starts nothing alone, and added after +# `run documentation` it starts the documentation again, with the preview. +set -euo pipefail + +: "${ACTION:?}" "${LABELS:?}" +LABEL="${LABEL:-}" + +has() { jq -e --arg l "$1" 'index($l) != null' <<< "$LABELS" > /dev/null; } + +# the run a label starts; nothing for a label that does not start any +entry() { + case "$1" in + "run ci github-runner") echo "CI.yml target=github" ;; + "run ci occidata-runner") echo "CI.yml target=occidata" ;; + "run ci kkt-runner") echo "CI.yml target=kkt" ;; + "run breakage") echo "Breakage.yml target=packages" ;; + "run breakage applications") echo "Breakage.yml target=applications" ;; + "run documentation") + if has "documentation push preview"; then + echo "Documentation.yml preview=true" + else + echo "Documentation.yml preview=false" + fi ;; + esac +} + +if [ "$ACTION" = labeled ]; then + if [ "$LABEL" = "documentation push preview" ]; then + has "run documentation" && entry "run documentation" + else + entry "$LABEL" + fi +else + while IFS= read -r label; do entry "$label"; done < <(jq -r '.[]' <<< "$LABELS") +fi +exit 0 diff --git a/scripts/label-dispatch/test.sh b/scripts/label-dispatch/test.sh new file mode 100755 index 0000000..d0c57fc --- /dev/null +++ b/scripts/label-dispatch/test.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +# Tests of plan.sh: bash scripts/label-dispatch/test.sh +set -uo pipefail +plan="$(dirname "$0")/plan.sh" +failed=0 + +# check