update-github-workflows

What is this?

Use this skill when changing CI behavior in .github/workflows/ or shared steps in .github/actions/. For action-version and SHA-pin updates alone, use update-github-actions. For Docker image changes, also follow update-docker-images.

Follow the shared skill guidance, including repository instructions and AI rules.

Table of Contents ᐞ

• What is this
  • Table of Contents
    • Repository workflow map
    • Workflow
    • Validation

Repository workflow map ᐞ

Read the current files before editing; this map is an orientation, not a replacement for their actual event filters and conditions:

• .github/workflows/main.yml: configuration/documentation lint, dependency and secret checks, Docker pin verification, static-analysis matrix, tests, and development/production image builds with vulnerability scanning. It handles pushes to master, PRs targeting any branch, a schedule, and manual runs.
• .github/workflows/dependency-review.yml: dependency review on PRs.
• .github/workflows/scorecard.yml: supply-chain analysis, artifact and SARIF uploads, with push, schedule, branch-protection, and manual triggers.
• .github/workflows/vulnerability-scan.yml: scheduled/manual production image build and vulnerability scan; it does not run on ordinary PRs.
• .github/actions/php-bootstrap/action.yml: shared Compose development container setup, Composer download cache, optional installation, and version reporting.

Workflow ᐞ

1. Identify the intended behavior and affected events, jobs, and callers. Read the relevant Make targets, scripts, bootstrap inputs, and configuration before adding shell commands. Reuse existing checks rather than creating a second implementation. Ask before changing event coverage, required-check identities, permissions, or the policy for blocking tests/builds.
2. Preserve event and execution semantics. Check PR base-branch versus push branch filters, schedule timing in UTC, manual-run inputs, job/step if expressions, and concurrency groups/cancellation. Do not assume the default branch is named main. Consider same-repository PRs, fork PRs, pushes, and non-PR events explicitly; not every event supplies a pull-request payload. Path filters or job renames can affect required checks; confirm repository rules when relevant rather than assuming they are defined in YAML.
3. Maintain the job dependency graph. In main.yml, ci-summary runs with always() and explicitly requires successful prerequisite results; tests and Docker builds depend on that gate. When adding, removing, or renaming a prerequisite, update its needs entry and result checks/messages together. Check failure, cancellation, and skipped-job paths, not only success. Do not use continue-on-error or permissive result checks to make a required failure appear green.
4. Preserve shared setup contracts. Inspect all callers before changing php-bootstrap defaults or input names. Its boolean-like inputs are strings compared with 'true'; preserve compatible caller values. The test job deliberately defers dependency installation and version reporting until after copying .env.gh-actions and generating JWT keys. The PHP runtime, extensions, and coverage driver come from the development Dockerfile, not runner PHP setup. Keep service health checks and the dynamically assigned MariaDB host port reachable via host.docker.internal and forwarded into the PHP container. Do not copy CI environment files over a developer's local configuration merely to validate a workflow edit.
5. Keep runner and command assumptions explicit. Check PHP requirements in composer.json and actual tools/extensions in the bootstrap. Inspect Makefile environment detection: local and hosted project commands execute inside the Compose PHP development service through Make targets. make ci-start starts that service without the application entrypoint or dependencies, and make ci-stop must run with always() after consumers. Docker/Compose checks and GitHub platform actions run on the host. Preserve YAML anchors and aliases in main.yml; changing an anchored checkout or hardening step affects every alias. Retain suitable timeouts and intentional matrix fail-fast behavior; inspect all matrix variants affected by a shared change.
6. Preserve trust boundaries and least-privilege intent. Keep external actions SHA-pinned and runner hardening in place. Review permissions at workflow and job scope, checkout credentials, cache keys/restore scope, and shell handling of untrusted event values. Do not switch to pull_request_target, execute untrusted PR code with privileged credentials, or expose secrets to make a job work. Pass untrusted values through quoted environment variables instead of interpolating them into shell source.
7. Preserve reporting and artifact contracts. External coverage/Sonar uploads run only after successful pushes to master, outside the core CI gate, and require their optional token. Keep core tests independent of those uploads. Verify producer paths match upload paths for coverage, analyzer reports, metrics, and SARIF; keep names unique across matrix jobs where required. Do not upload JWT keys, environment secrets, or unrelated workspace contents. Keep vulnerability thresholds and scan failure behavior unless a policy change is explicitly requested.
8. Update directly related contributor or AI guidance when CI commands or required checks change, including AI rules where applicable. Delegate pin verification to the action-update skill rather than duplicating that procedure. Do not push, dispatch workflows, or open a PR unless requested.