--- name: update-vortex-ci-runner description: Use when testing a canary build of 'drevops/ci-runner' against a Vortex project before official release, or when incrementing the pinned 'drevops/ci-runner' version after a new release. Triggers on phrases like 'test ci-runner canary', 'update ci-runner', 'switch ci-runner to canary', 'bump ci-runner to X.Y.Z'. user-invocable: true --- # Vortex Update CI Runner Two-phase workflow for verifying a new `drevops/ci-runner` release on a Vortex-based Drupal project: - **Phase 1 (Canary):** Switch all `drevops/ci-runner` image references to `:canary` (no SHA pin), open a PR, monitor CI. If green, STOP and notify the user so they can cut the official release. - **Phase 2 (Release):** After the user confirms a release version, roll the same PR forward to pin `:NEW_VERSION@sha256:NEW_SHA`, push, monitor CI. On green, notify the user the PR is ready to merge. ## When to Use - User says 'test ci-runner canary' / 'switch ci-runner to canary' / 'try the new ci-runner'. - User says 'update ci-runner to X.Y.Z' (skip to Phase 2 if no canary needed). - Vortex release prep needs a ci-runner verification. Do NOT use for `uselagoon/*` images (Renovate handles those) or `ci-builder` (different image). ## Prerequisites - Working in a Vortex-based project (look for `.vortex/` directory or `drevops/ci-runner` references). - `gh` CLI authenticated. - Docker available (only needed for the Phase 2 SHA lookup). - Clean working tree. ## Phase 1: Canary ### 1. Discover references The file list is not fixed: older or downstream projects may have it in more places. Always rediscover. ```bash grep -rln "drevops/ci-runner" --include="*.yml" . ``` Repeat for `*.yaml` and `Dockerfile*`. **Exclude `*/tests/Fixtures/*` and `*/test/Fixtures/*` paths** since those are snapshots used by installer tests, not live CI configs. Record the current version and SHA before changing anything: you need to know what you are rolling forward from in case of rollback. ### 2. Branch ```bash git checkout -b feature/update-ci-runner ``` This branch is reused for Phase 2; do not create a new branch when the release version is provided. ### 3. Replace image references For every non-fixture file from Step 1, replace: ```text drevops/ci-runner:@sha256: ``` with: ```text drevops/ci-runner:canary ``` **Drop the SHA pin in canary mode.** Pinning a SHA defeats the canary: CI re-runs would test the same frozen build, not whatever the `canary` tag currently points to. The whole point of the canary phase is to track a moving target. Use the `Edit` tool with `replace_all: true` per file. Verify with grep afterwards: the only remaining hits should be in fixture paths. ### 4. Commit and push Stage specific files (never `git add .`): ```bash git add .github/workflows/build-test-deploy.yml ``` ```bash git commit -m "Switched 'drevops/ci-runner' to 'canary' for verification." ``` ```bash git push -u origin feature/update-ci-runner ``` ### 5. Open PR Invoke the `/open-pr` skill. PR title: ```text Tested 'drevops/ci-runner' canary build. ``` PR body should note: this is a canary test (NOT for merge yet), the previous pinned version, files changed, and that the next step is for the user to release a new `drevops/ci-runner` once CI passes. ### 6. Monitor CI Watch GitHub Actions via `gh pr checks ` and CircleCI via the PR link. **On failure:** Diagnose before reporting. Common causes: - **Tool version drift** in canary (PHP, Node, Composer bumped in the ci-runner image but pinned in project configs: `composer.json` `config.platform.php`, `phpstan.neon` `phpVersion`, `phpcs.xml` `testVersion`). - A tool removed from the canary image. - Cache key issues (rare: cache keys are tied to Lagoon versions, not ci-runner). - Image pull / registry timeout. Report with: failing job name, failing step, ~30 lines of the most relevant log, and your hypothesis. Do not paste raw logs without a hypothesis. **On success:** STOP. Do not merge. Tell the user: > Canary verification passed: CI is green on ``. Ready for you to cut the new `drevops/ci-runner` release. Let me know the new version (e.g. `26.4.0`) when ready. ## Phase 2: Release Pin Triggered when the user confirms a new released version (e.g. 'released as 26.4.0'). ### 1. Get the SHA digest ```bash docker pull drevops/ci-runner: ``` ```bash docker inspect --format="{{index .RepoDigests 0}}" drevops/ci-runner: ``` The output is `drevops/ci-runner@sha256:`. Record ``. If docker is unavailable, use `docker manifest inspect drevops/ci-runner:` and read the linux/amd64 digest. ### 2. Replace canary references Rediscover files (rerun the grep from Phase 1 Step 1). Replace: ```text drevops/ci-runner:canary ``` with: ```text drevops/ci-runner:@sha256: ``` ### 3. Commit and push on the same branch ```bash git commit -m "Updated 'drevops/ci-runner' to ''." ``` ```bash git push ``` ### 4. Update PR metadata ```bash gh pr edit --title "Updated 'drevops/ci-runner' to ''." ``` Add a comment summarising the canary -> release transition. ### 5. Monitor CI Same as Phase 1 Step 6. On success: > CI green on pinned ``. PR `` ready to merge. Do NOT merge: the user merges. ## Red Flags - About to pin a SHA in Phase 1: don't. Canary needs the moving tag. - About to edit a file under `tests/Fixtures/`: don't. Those are test snapshots. - About to merge the PR: don't. User merges. - About to use `gh pr create`: don't. Use `/open-pr`. - About to start Phase 2 without Phase 1 CI green: confirm with user first. - Hardcoding the file list from this skill: don't. Always grep first. ## Common Mistakes | Mistake | Fix | |---------|-----| | Hardcoded list of files | Always grep: the list grows over time | | Included fixture files in edits | Exclude fixture snapshot paths only (for example `*/tests/Fixtures/*` and `*/test/Fixtures/*`) | | Kept SHA pin in canary phase | Strip SHA: canary tag must be unpinned to test moving target | | Used `git add .` | Stage specific files only | | Reported CI failure raw | Read failing step, form a hypothesis, then report | | Created PR via `gh pr create` | Use `/open-pr` skill | | New branch for Phase 2 | Reuse the Phase 1 branch and PR |