From cd34cfe9cacd0e434416744cf67d0edf40b2d22b Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Mon, 27 Apr 2026 11:24:59 +0000 Subject: [PATCH] docs: update documentation for features merged 2026-04-27 - Add deployment_status trigger section to triggers.md (from #28549) - Add deployment state filter (state:) and NL shorthands - Add deployment incident monitor example - Update Playwright visual regression example with dev server setup pattern (from #28550) Co-Authored-By: Claude Sonnet 4.6 --- docs/src/content/docs/reference/playwright.md | 58 +++++++++++- docs/src/content/docs/reference/triggers.md | 94 +++++++++++++++++++ 2 files changed, 149 insertions(+), 3 deletions(-) diff --git a/docs/src/content/docs/reference/playwright.md b/docs/src/content/docs/reference/playwright.md index 2744a4fdc3c..cbd1df255d8 100644 --- a/docs/src/content/docs/reference/playwright.md +++ b/docs/src/content/docs/reference/playwright.md @@ -105,20 +105,56 @@ Create an issue for each category of problems found. ### Visual Regression Testing +Pin to a specific version and use `steps:` to start the application before the agent runs. This is the recommended pattern when testing a local dev server. + ```aw wrap --- on: pull_request: types: [opened, synchronize] + paths: + - 'docs/src/**/*.css' + - 'docs/src/**/*.tsx' + - 'docs/src/**/*.astro' + - 'docs/astro.config.mjs' + +steps: + - name: Checkout repository + uses: actions/checkout@v6 + with: + persist-credentials: false + - name: Install dependencies + working-directory: ./docs + run: npm ci + - name: Build documentation + working-directory: ./docs + run: npm run build + - name: Start dev server + working-directory: ./docs + run: npm run dev & + - name: Wait for dev server + run: | + for i in $(seq 1 30); do + if curl -sf http://localhost:4321/ > /dev/null 2>&1; then + echo "Dev server is ready"; exit 0 + fi + sleep 1 + done + exit 1 tools: playwright: + version: "v1.52.0" + bash: + - "npm *" + - "curl http://localhost:*" network: allowed: - defaults - playwright - - github + - local + - node permissions: contents: read @@ -126,15 +162,31 @@ permissions: safe-outputs: add-comment: max: 1 + noop: --- # Visual Regression Check -Compare screenshots of the documentation site before and after this PR. +The documentation site dev server is running at http://localhost:4321/. + +Check for visual regressions on these pages: home, getting-started, and reference. + +Test on multiple viewports: +- Mobile: 375×812 +- Tablet: 768×1024 +- Desktop: 1440×900 -Test on multiple viewports (mobile, tablet, desktop) and report any visual differences. +Take screenshots at each viewport and compare against baseline. Report any visual differences as a pull request comment, including screenshots. If there are no regressions, call noop. ``` +**Key patterns for dev server visual regression:** + +- **Path filter** — restricts the trigger to runs affecting frontend assets, avoiding noise on unrelated changes. +- **`steps:`** — run before the agent. Use them to install dependencies, build, start the server, and poll until it is ready. The agent only starts after all steps succeed. +- **Version pin** — pin Playwright to a specific version (`v1.52.0`) to prevent baseline drift from browser engine upgrades mid-test. +- **`local` network identifier** — allows the Playwright container to reach `localhost`/`127.0.0.1` where the dev server runs. Required when testing local servers. +- **`bash` allowlist** — restricts the `bash` tool to `npm *` and `curl http://localhost:*` only, keeping the tool surface minimal. + ### End-to-End Testing ```aw wrap diff --git a/docs/src/content/docs/reference/triggers.md b/docs/src/content/docs/reference/triggers.md index 9a1e79dc499..9fbb59f02b2 100644 --- a/docs/src/content/docs/reference/triggers.md +++ b/docs/src/content/docs/reference/triggers.md @@ -279,6 +279,97 @@ Workflows with `workflow_run` triggers include automatic security protections: See the [Security Architecture](/gh-aw/introduction/architecture/) for details. +### Deployment Status Triggers (`deployment_status:`) + +Trigger workflows when a GitHub deployment status changes. [Full event reference](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status). + +```yaml wrap +on: + deployment_status: +``` + +#### State Filtering (`state:`) + +Use `state:` to restrict the trigger to specific deployment states. The compiler compiles this into a guarded `if:` condition so the workflow only runs for the matching states. Other combined triggers (such as `workflow_dispatch`) are not blocked by the guard. + +```yaml wrap +on: + deployment_status: + state: failure # Single state +``` + +```yaml wrap +on: + deployment_status: + state: [error, failure] # Multiple states + workflow_dispatch: # Safely combined — guard ensures dispatch passes through +``` + +Valid `state` values: `error`, `failure`, `pending`, `success`, `inactive`, `in_progress`, `queued`, `waiting`. + +> [!NOTE] +> The `state` field compiles into a GitHub Actions `if:` condition: `github.event_name != 'deployment_status' || (github.event.deployment_status.state == 'failure')`. This means the workflow still runs when triggered by other events in the same `on:` block. + +#### Required Permissions + +Workflows triggered by `deployment_status` need `deployments: read` to access the event payload: + +```yaml wrap +permissions: + contents: read + deployments: read +``` + +#### Natural Language Shorthands + +```yaml wrap +on: "deployment failed" # deployment_status with state == 'failure' +on: "deployment error" # deployment_status with state == 'error' +on: "deployment failed or error" # deployment_status with state == 'failure' or 'error' +``` + +These shorthands also include `workflow_dispatch` automatically. + +#### Deployment Incident Monitor Example + +```aw wrap +--- +on: + deployment_status: + state: [error, failure] + workflow_dispatch: +permissions: + contents: read + actions: read + deployments: read +tools: + github: + toolsets: [repos, actions] +safe-outputs: + create-issue: + expires: 7d + title-prefix: "[Incident] " + labels: [incident, deployment-failure] + close-older-issues: true + skip-if-match: 'is:issue is:open label:incident label:deployment-failure' + noop: +--- + +# Deployment Incident Monitor + +A deployment to ${{ github.event.deployment.environment }} has failed with state: ${{ github.event.deployment_status.state }}. + +Investigate the root cause: +1. Check the deployment workflow logs for the failing step +2. Review recent commits to the deployed branch for potential causes +3. Check if this environment has had recent failures (look for existing incident issues) + +If a new incident is found, create an issue summarising the failure, the likely root cause, and the recommended next step. +If an incident issue for this deployment already exists, call noop. +``` + +See the [Natural Language Shorthands](#other-shorthands) section for additional shorthand formats. + ### Command Triggers (`slash_command:`) The `slash_command:` trigger creates workflows that respond to `/command-name` mentions in issues, pull requests, and comments. @@ -727,6 +818,9 @@ on: dependabot pull request # PR from Dependabot (adds actor condition) on: security alert # Code scanning alert on: code scanning alert # Alias for security alert (code scanning alert) on: api dispatch custom-event # Repository dispatch with custom event type +on: "deployment failed" # deployment_status with state == 'failure' guard +on: "deployment error" # deployment_status with state == 'error' guard +on: "deployment failed or error" # deployment_status with state == 'failure' or 'error' guard ``` ## Related Documentation