From c32bbc19ee104557c23de60f4bc6f58e1fc48ab2 Mon Sep 17 00:00:00 2001 From: priyankatiwari08 Date: Wed, 20 May 2026 16:26:22 +0530 Subject: [PATCH 1/2] Add gh-aw lock-file enforcement (instructions + CI guard) - Add path-scoped instruction file under .github/instructions/ that applies to .github/workflows/**/*.md, so Copilot and coding agents auto-load the rule: edits to a workflow .md MUST include the regenerated sibling .lock.yml in the same PR. - Add verify-aw-lock CI workflow that runs `gh aw compile` and fails the PR if any .lock.yml is stale. Follow-up to the runtime failure seen in PR #4279. --- .../agentic-workflows.instructions.md | 49 +++++++++++++++++++ .github/workflows/verify-aw-lock.yml | 32 ++++++++++++ 2 files changed, 81 insertions(+) create mode 100644 .github/instructions/agentic-workflows.instructions.md create mode 100644 .github/workflows/verify-aw-lock.yml diff --git a/.github/instructions/agentic-workflows.instructions.md b/.github/instructions/agentic-workflows.instructions.md new file mode 100644 index 0000000000..6a42c0dce3 --- /dev/null +++ b/.github/instructions/agentic-workflows.instructions.md @@ -0,0 +1,49 @@ +--- +applyTo: ".github/workflows/**/*.md" +description: Rules for editing gh-aw agentic workflow Markdown files. +--- + +# Agentic Workflow Edit Rules (`gh aw`) + +This repository authors GitHub Actions agentic workflows in Markdown using +[`gh aw`](https://github.com/githubnext/gh-aw). Each workflow `.md` file under +`.github/workflows/` compiles to a sibling `.lock.yml`, and **only the +`.lock.yml` is executed by GitHub Actions at runtime.** + +## Mandatory rule + +Whenever you create, edit, rename, or delete a file matching +`.github/workflows/**/*.md`, you **MUST**, in the **same commit / PR**: + +1. Run `gh aw compile` from the repository root. +2. Stage and commit the regenerated sibling `.lock.yml`. +3. If you deleted a workflow `.md`, also delete its `.lock.yml`. + +If the `.lock.yml` is stale or missing, the workflow fails at runtime +(see PR #4279 for the exact failure mode). The +`Verify gh aw lock files` CI check will block the PR in that case. + +## How to verify locally + +```bash +gh aw compile +git status # both the .md and .lock.yml should appear +gh aw compile # second run must be a no-op (clean diff) +``` + +## Code-review checklist + +When reviewing a PR that touches `.github/workflows/**/*.md`: + +- [ ] A matching `.lock.yml` is updated in the same PR. +- [ ] `gh aw compile` produces no further diff on top of the PR. +- [ ] If new tools, network endpoints, or permissions are added in the `.md`, + they are present in the regenerated `.lock.yml`. + +## Out of scope + +- Do **not** hand-edit `.lock.yml` files. They are generated; edit the `.md` + source and recompile. +- For deeper authoring guidance (creating, debugging, upgrading workflows), + invoke the `agentic-workflows` agent at + `.github/agents/agentic-workflows.agent.md`. diff --git a/.github/workflows/verify-aw-lock.yml b/.github/workflows/verify-aw-lock.yml new file mode 100644 index 0000000000..0066636fce --- /dev/null +++ b/.github/workflows/verify-aw-lock.yml @@ -0,0 +1,32 @@ +name: Verify gh aw lock files + +on: + pull_request: + paths: + - '.github/workflows/**/*.md' + - '.github/workflows/**/*.lock.yml' + +permissions: + contents: read + +jobs: + verify: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install gh-aw extension + env: + GH_TOKEN: ${{ github.token }} + run: gh extension install githubnext/gh-aw + + - name: Recompile agentic workflows + run: gh aw compile + + - name: Fail if any .lock.yml is stale + run: | + if ! git diff --exit-code -- '.github/workflows/**/*.lock.yml'; then + echo "::error::A .github/workflows/**/*.md file changed but its .lock.yml is stale." + echo "::error::Run 'gh aw compile' locally and commit the regenerated .lock.yml in this PR." + exit 1 + fi From 8beb72f83a5f6fd6cd96cc8ce4189903c8339fd6 Mon Sep 17 00:00:00 2001 From: priyankatiwari08 Date: Wed, 20 May 2026 17:19:52 +0530 Subject: [PATCH 2/2] Address Copilot review comments on verify-aw-lock workflow - Pin gh-aw to v0.72.1 via github/gh-aw-actions/setup-cli to match the version already used by .github/workflows/copilot-setup-steps.yml, so the CI compilation matches the repo's expected compiler version and avoids spurious diffs from version drift. - Rewrite the failure message to describe the actual checked condition (lock files out of date relative to their compiled output). The previous wording wrongly implied only a .md change could trigger it, but the workflow also runs when a .lock.yml file is touched directly. --- .github/workflows/verify-aw-lock.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/verify-aw-lock.yml b/.github/workflows/verify-aw-lock.yml index 0066636fce..1d37e610e8 100644 --- a/.github/workflows/verify-aw-lock.yml +++ b/.github/workflows/verify-aw-lock.yml @@ -16,17 +16,17 @@ jobs: - uses: actions/checkout@v4 - name: Install gh-aw extension - env: - GH_TOKEN: ${{ github.token }} - run: gh extension install githubnext/gh-aw + uses: github/gh-aw-actions/setup-cli@bc56a0cad2f450c562810785ef38649c04db812a # v0.72.1 + with: + version: v0.72.1 - name: Recompile agentic workflows run: gh aw compile - - name: Fail if any .lock.yml is stale + - name: Fail if any .lock.yml is out of date run: | if ! git diff --exit-code -- '.github/workflows/**/*.lock.yml'; then - echo "::error::A .github/workflows/**/*.md file changed but its .lock.yml is stale." - echo "::error::Run 'gh aw compile' locally and commit the regenerated .lock.yml in this PR." + echo "::error::One or more .github/workflows/**/*.lock.yml files are out of date relative to their .md source (running 'gh aw compile' produced a diff)." + echo "::error::Run 'gh aw compile' locally and commit the regenerated .lock.yml files in this PR." exit 1 fi