| 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.
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
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:
drevops/ci-runner:<VERSION>@sha256:<HASH>
with:
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 .):
git add .github/workflows/build-test-deploy.yml
git commit -m "Switched 'drevops/ci-runner' to 'canary' for verification."
git push -u origin feature/update-ci-runner
5. Open PR
Invoke the /open-pr skill. PR title:
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 <PR> 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 <PR URL>. 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
docker pull drevops/ci-runner:<NEW_VERSION>
docker inspect --format="{{index .RepoDigests 0}}" drevops/ci-runner:<NEW_VERSION>
The output is drevops/ci-runner@sha256:<HASH>. Record <HASH>.
If docker is unavailable, use docker manifest inspect drevops/ci-runner:<NEW_VERSION> and read the linux/amd64 digest.
2. Replace canary references
Rediscover files (rerun the grep from Phase 1 Step 1). Replace:
drevops/ci-runner:canary
with:
drevops/ci-runner:<NEW_VERSION>@sha256:<NEW_HASH>
3. Commit and push on the same branch
git commit -m "Updated 'drevops/ci-runner' to '<NEW_VERSION>'."
git push
4. Update PR metadata
gh pr edit <PR> --title "Updated 'drevops/ci-runner' to '<NEW_VERSION>'."
Add a comment summarising the canary -> release transition.
5. Monitor CI
Same as Phase 1 Step 6. On success:
CI green on pinned <NEW_VERSION>. PR <URL> 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 |
