This directory hosts every GitHub Actions workflow that runs in microsoft/testfx, including the AI-powered agentic workflows generated with the gh aw CLI.

Two file styles coexist:

• Regular workflows — plain *.yml files authored by hand and consumed directly by GitHub Actions.
• Agentic workflows — *.md sources compiled to companion *.lock.yml files via gh aw compile. The .md file is the source of truth; the .lock.yml is generated and must be regenerated whenever the source changes.

Reusable building blocks for agentic workflows live under shared/ and are imported through the imports: frontmatter field.

# Install the gh-aw CLI extension (once per machine)
gh extension install github/gh-aw

# Compile a single workflow after editing its .md source. Strict mode is the
# default — keep it that way. NEVER set `strict: false` in frontmatter.
gh aw compile <workflow-id>

# When in doubt, force strict-mode validation across all workflows
gh aw compile --strict

# Trigger a workflow on demand
gh aw run <workflow-id>             # interactive
gh aw run <workflow-id> --ref main  # against a specific branch

# Inspect or debug a recent run
gh aw logs <workflow-id>
gh aw audit <run-id>

For deeper guidance — creating, updating, debugging, upgrading, or wrapping MCP servers — see the dispatcher .github/agents/agentic-workflows.agent.md, which routes to the canonical gh-aw prompts.

Agentic workflows authenticate through repository secrets:

1. Replace COPILOT_GITHUB_TOKEN with copilot-requests: write. When a workflow's permissions: block grants copilot-requests: write, gh-aw authenticates Copilot inference with the per-run GitHub Actions token and bills through the org's Copilot subscription — no PAT, no secret to rotate. When the permission is present any COPILOT_GITHUB_TOKEN value is ignored for inference.

permissions:
  contents: read
  copilot-requests: write

2. Replace GH_AW_GITHUB_TOKEN with an org-owned GitHub App. A GitHub App mints a short-lived token at the start of each run, scoped to the job's permissions:, and automatically revoked when the run ends (even on failure) — which satisfies the org's short-PAT policy without any manual rotation. A single App can serve every GitHub auth need in these workflows (MCP reads and safe-output writes); only COPILOT_GITHUB_TOKEN cannot use an App (covered by option 1 instead).

Set it up once (requires org admin to create/install the App):

1. Create a GitHub App owned by the microsoft org (Settings → Developer settings → GitHub Apps). Grant the read/write repository permissions the workflows need (e.g. Contents, Issues, Pull requests), generate a private key (.pem), and install the App on microsoft/testfx.

2. Store the App ID as a repository variable and the private key as a secret:

   gh variable set APP_ID   --repo microsoft/testfx --body "<app-id>"
   gh secret   set APP_PRIVATE_KEY --repo microsoft/testfx --body "$(cat path/to/private-key.pem)"

3. Reference the App in the workflow frontmatter (source .md, then recompile):

   tools:
     github:
       toolsets: [repos, issues, pull_requests]
       github-app:
         client-id: ${{ vars.APP_ID }}
         private-key: ${{ secrets.APP_PRIVATE_KEY }}
   # and/or, for write-backs:
   safe-outputs:
     github-app:
       client-id: ${{ vars.APP_ID }}
       private-key: ${{ secrets.APP_PRIVATE_KEY }}

   Add ignore-if-missing: true under github-app: if a workflow must still run on fork PRs (where App secrets are unavailable); it then falls back to GH_AW_GITHUB_TOKEN || GITHUB_TOKEN.

See the upstream reference: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/auth.mdx#using-a-github-app-for-authentication.

Historically the four local workflows that read issues/PRs (add-tests.md, weekly-issue-activity.md, shared/address-review-shared.md, and shared/grade-tests-shared.md) set lockdown: true on the GitHub MCP tool. Lockdown mode rejected the default GITHUB_TOKEN and forced a custom PAT (GH_AW_GITHUB_MCP_SERVER_TOKEN || GH_AW_GITHUB_TOKEN || GITHUB_TOKEN), so a single missing/expired PAT failed all of them at activation.

lockdown: is deprecated upstream in favour of integrity filtering (min-integrity). These workflows already declared min-integrity: none (they intentionally examine any issue/PR), so lockdown: true only added the PAT requirement. It has been dropped; the content-filtering behaviour is unchanged, and the default GITHUB_TOKEN now suffices unless a workflow needs elevated access (then use the GitHub App above).

Reusable agentic-workflow snippets imported via imports: in workflow frontmatter:

• Strict mode is mandatory. Workflow frontmatter must not set strict: false. When in doubt, run gh aw compile --strict.
• Source of truth. Edit the .md file (and any imported shared/*.md); never the .lock.yml.
• One change, one compile. After editing an agentic workflow source, run gh aw compile <workflow-id> and commit the regenerated .lock.yml in the same change.
• Same applies to Dependabot updates that touch generated manifests (e.g. package.json / requirements.txt / go.mod) if gh aw compile ever emits them under .github/workflows/: never merge those PRs directly; update the source .md files and rerun gh aw compile --dependabot to bundle the fixes.
• Pinned actions only. Strict mode pins every uses: reference to a SHA; the compiler enforces this.
• Minimal permissions. Workflows declare the least privilege they need; write capabilities flow through gh-aw safe-outputs: rather than direct permissions: write-all.