diff --git a/.github/agents/agentic-workflows.agent.md b/.github/agents/agentic-workflows.agent.md index e34a4da6123..c0f21877e1b 100644 --- a/.github/agents/agentic-workflows.agent.md +++ b/.github/agents/agentic-workflows.agent.md @@ -18,6 +18,7 @@ This is a **dispatcher agent** that routes your request to the appropriate speci - **Creating report-generating workflows**: Routes to `report` prompt — consult this whenever the workflow posts status updates, audits, analyses, or any structured output as issues, discussions, or comments - **Creating shared components**: Routes to `create-shared-agentic-workflow` prompt - **Fixing Dependabot PRs**: Routes to `dependabot` prompt — use this when Dependabot opens PRs that modify generated manifest files (`.github/workflows/package.json`, `.github/workflows/requirements.txt`, `.github/workflows/go.mod`). Never merge those PRs directly; instead update the source `.md` files and rerun `gh aw compile --dependabot` to bundle all fixes +- **Analyzing test coverage**: Routes to `test-coverage` prompt — consult this whenever the workflow reads, analyzes, or reports on test coverage data from PRs or CI runs Workflows may optionally include: @@ -118,6 +119,16 @@ When you interact with this agent, it will: - "Bundle and close the Dependabot PRs for workflow dependencies" - "Update @playwright/test to fix the Dependabot PR" +### Analyze Test Coverage +**Load when**: The workflow reads, analyzes, or reports test coverage — whether triggered by a PR, a schedule, or a slash command. Always consult this prompt before designing the coverage data strategy. + +**Prompt file**: https://github.com/github/gh-aw/blob/main/.github/aw/test-coverage.md + +**Use cases**: +- "Create a workflow that comments coverage on PRs" +- "Analyze coverage trends over time" +- "Add a coverage gate that blocks PRs below a threshold" + ## Instructions When a user interacts with you: diff --git a/.github/aw/create-agentic-workflow.md b/.github/aw/create-agentic-workflow.md index a89962aad14..d2a8fe36153 100644 --- a/.github/aw/create-agentic-workflow.md +++ b/.github/aw/create-agentic-workflow.md @@ -577,6 +577,9 @@ Based on the parsed requirements, determine: - Issue automation → `on: issues: types: [opened, edited]` (add `workflow_dispatch:` manually if manual runs needed) - PR automation → `on: pull_request: types: [opened, synchronize]` (add `workflow_dispatch:` manually if manual runs needed) - Scheduled tasks → `on: schedule: daily on weekdays` (prefer weekdays to avoid Monday backlog - workflow_dispatch auto-added for fuzzy schedules only) + - **External deployment monitoring** (Heroku, Vercel, Railway, Fly.io, etc.) → `on: deployment_status:` with `if: ${{ github.event.deployment_status.state == 'failure' }}` — use this when third-party services post deployment status back to GitHub. See reference: @.github/aw/deployment-status.md + - **GitHub Actions pipeline monitoring** → `on: workflow_run:` with `if: ${{ github.event.workflow_run.conclusion == 'failure' }}` — use this when monitoring other GitHub Actions workflows in the same repo + - **`deployment_status` vs `workflow_run`**: Use `deployment_status` for **external deployment services** that integrate with the GitHub Deployments API; use `workflow_run` for **GitHub Actions-internal** pipelines. Never use `workflow_run` as a workaround for external deployment failures. - **Note**: `workflow_dispatch:` is automatically added ONLY for fuzzy schedules (`daily`, `weekly`, etc.). For other triggers, add it explicitly if manual execution is desired. 3. **Tools**: Determine required tools: - **`bash` and `edit` are enabled by default** - No need to add (sandboxed by AWF) diff --git a/.github/aw/deployment-status.md b/.github/aw/deployment-status.md new file mode 100644 index 00000000000..f83e849926e --- /dev/null +++ b/.github/aw/deployment-status.md @@ -0,0 +1,62 @@ +--- +description: Reference pattern for monitoring external deployment failures using the deployment_status trigger and creating incident issues automatically. +--- + +# Deployment Status Monitoring + +Consult this file when creating an agentic workflow that responds to external deployment failures from services like Heroku, Vercel, Railway, or Fly.io that post deployment status back to GitHub. + +## Trigger and Frontmatter + +Use the `deployment_status` trigger with an `if:` condition to filter to failed deployments only: + +```yaml +on: + deployment_status: +if: ${{ github.event.deployment_status.state == 'failure' }} +permissions: + contents: read + issues: read + deployments: read +tools: + github: + toolsets: [default] +safe-outputs: + create-issue: + expires: 1d + title-prefix: "[Deployment Failure] " + close-older-issues: true + noop: +``` + +## Available Event Context + +The following expressions are available in the prompt body: + +| Expression | Description | +|---|---| +| `${{ github.event.deployment.environment }}` | Target environment (e.g. `production`) | +| `${{ github.event.deployment_status.state }}` | Status (`failure`, `success`, `error`, etc.) | +| `${{ github.event.deployment_status.target_url }}` | URL to the external service deployment logs | +| `${{ github.event.deployment_status.description }}` | Human-readable error message from the service | +| `${{ github.event.deployment.ref }}` | Branch or tag that was deployed | +| `${{ github.event.deployment.sha }}` | Commit SHA that was deployed | +| `${{ github.event.deployment.creator.login }}` | GitHub user who triggered the deployment | + +## Agent Instructions Pattern + +```markdown +A deployment to **${{ github.event.deployment.environment }}** has failed. + +1. **Verify the failure**: Confirm `${{ github.event.deployment_status.state }}` is `failure`. If not, call `noop` and stop. +2. **Gather context**: Review ref (`${{ github.event.deployment.ref }}`), SHA (`${{ github.event.deployment.sha }}`), and error description (`${{ github.event.deployment_status.description }}`). +3. **Check for duplicates**: Search open issues with the `[Deployment Failure]` title prefix. +4. **Create an incident issue** if none exists, including environment, ref/SHA, deployment URL, error details, and suggested next steps. + +Use `noop` if the deployment did not fail or a duplicate issue already exists. +``` + +## When to Use `deployment_status` vs `workflow_run` + +- **`deployment_status`**: External services (Heroku, Vercel, Railway, Fly.io) that integrate with the GitHub Deployments API — they post a deployment status event back to GitHub when a deploy finishes. +- **`workflow_run`**: In-repo GitHub Actions pipelines — use when reacting to the success or failure of another Actions workflow in the same repository.