diff --git a/.github/workflows/shared-drift.yml b/.github/workflows/shared-drift.yml new file mode 100644 index 0000000..92f669b --- /dev/null +++ b/.github/workflows/shared-drift.yml @@ -0,0 +1,57 @@ +# The shared-drift check, for the siblings to call instead of each carrying its own copy: +# +# jobs: +# shared-drift: +# uses: SDNick484/mcp-server-shared/.github/workflows/shared-drift.yml@<40-char SHA> # v0.1.0 +# +# The caller's own `on:` decides when it runs; this workflow only defines the job. It checks out +# the *caller's* repo (a called workflow runs in the caller's context) and runs that repo's own +# scripts/sync_shared.py, so a sibling is checked by the script version its lock pins: +# - always: --check (files match the commit in shared.lock) +# - on schedule / workflow_dispatch: --check --latest (... and that commit is main's head) +# Pass `latest: true` to run the second check on other events too. +# +# Pin the ref to a commit SHA with the tag as a comment (Dependabot's github-actions ecosystem +# bumps both, as for any action). This repo's own CI doesn't call it: it has no shared.lock. +name: shared-drift + +on: + workflow_call: + inputs: + latest: + description: Also check the lock against mcp-server-shared main, whatever the event + type: boolean + default: false + python-version: + description: Python for sync_shared.py; the oldest supported keeps the stdlib-only script honest + type: string + default: "3.11" + +# A called workflow can only narrow the caller's token, never widen it. Read is all this needs. +permissions: + contents: read + +jobs: + shared-drift: + runs-on: ubuntu-latest + timeout-minutes: 10 + # Job-level, with its own suffix: in a called workflow github.workflow is the *caller's* name, + # and a group equal to the caller's own workflow-level group deadlocks the run. The event is in + # the group, and only PR runs cancel: a push to main must not cancel the weekly --latest check. + concurrency: + group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}-shared-drift + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + env: + GITHUB_TOKEN: ${{ github.token }} # for api.github.com's rate limit; raw files are fetched without it + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false # nothing here pushes + - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0 + with: + python-version: ${{ inputs.python-version }} + - name: Shared files match the locked commit + run: python scripts/sync_shared.py --check + - name: Shared files match mcp-server-shared main + if: inputs.latest || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' + run: python scripts/sync_shared.py --check --latest diff --git a/README.md b/README.md index ce99cc3..aecad8d 100644 --- a/README.md +++ b/README.md @@ -203,8 +203,39 @@ schedule: - cron: "0 9 * * 1" # 09:00 UTC every Monday ``` -This runs `python scripts/sync_shared.py --check-latest`, which checks whether `shared.lock` -is behind `mcp-server-shared`'s `main` branch. +On that run the shared-drift job adds `python scripts/sync_shared.py --check --latest`, which +checks whether `shared.lock` is behind `mcp-server-shared`'s `main` branch. + +### The drift job is a reusable workflow, not a synced file + +`.github/workflows/shared-drift.yml` here is the one definition of the shared-drift job +(`on: workflow_call`). A sibling's `ci.yml` calls it, pinned like an action: + +```yaml +jobs: + shared-drift: + uses: SDNick484/mcp-server-shared/.github/workflows/shared-drift.yml@<40-char SHA> # v0.1.0 +``` + +It checks out the caller and runs the caller's own `sync_shared.py --check`, plus `--check --latest` +on `schedule`/`workflow_dispatch` (or with `latest: true`). Read-only token, SHA-pinned actions, +`timeout-minutes`, and a job-level `concurrency` group (a called workflow sharing the caller's +workflow-level group deadlocks, since `github.workflow` there is the caller's name). The group is +per event and only PR runs cancel, so a push to `main` can't cancel the weekly `--latest` check. + +The alternative was to make the workflow a synced file, like the modules. Why not: + +| | Reusable workflow (chosen) | Synced template | +|---|---|---| +| Copies | none; one SHA per sibling in `ci.yml` | one file per sibling, checked by `--check` | +| CI-time dependency on this repo | yes, but `--check` already fetches from here at CI time | none beyond what `--check` already has | +| Sibling-specific triggers | stay in the sibling's `ci.yml` | one file for all: same schedule everywhere, or templating | +| Pushing a sync | an ordinary commit | touches `.github/workflows/`: needs a token with `workflow` scope | +| Updating | Dependabot bumps the SHA (and `# vX` comment) once `main` is tagged | the next `sync_all_siblings.py update` | +| Pins to keep straight | two: `shared.lock` and the `uses:` SHA | one | + +The two-pins cost is small: the workflow changes rarely, and whichever SHA it is pinned to, it runs +the sibling's own sync script against the sibling's own lock. ### Why not fail normal PRs when the lock is behind?