diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index c415fbb2742..a997a224e4b 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -176,6 +176,7 @@ export default defineConfig({ { label: 'Reusing Workflows', link: '/guides/packaging-imports/' }, { label: 'Using MCPs', link: '/guides/mcps/' }, { label: 'Web Search', link: '/guides/web-search/' }, + { label: 'Playwright Screenshots', link: '/guides/playwright-screenshots/' }, ], }, { diff --git a/docs/src/content/docs/agent-factory-status.mdx b/docs/src/content/docs/agent-factory-status.mdx index dd3b9e0606a..39c3d116fc4 100644 --- a/docs/src/content/docs/agent-factory-status.mdx +++ b/docs/src/content/docs/agent-factory-status.mdx @@ -158,6 +158,7 @@ These are experimental agentic workflows used by the GitHub Next team to learn, | [Typist - Go Type Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/typist.md) | claude | [![Typist - Go Type Analysis](https://github.com/github/gh-aw/actions/workflows/typist.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/typist.lock.yml) | `0 11 * * 1-5` | - | | [Ubuntu Actions Image Analyzer](https://github.com/github/gh-aw/blob/main/.github/workflows/ubuntu-image-analyzer.md) | copilot | [![Ubuntu Actions Image Analyzer](https://github.com/github/gh-aw/actions/workflows/ubuntu-image-analyzer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/ubuntu-image-analyzer.lock.yml) | - | - | | [Video Analysis Agent](https://github.com/github/gh-aw/blob/main/.github/workflows/video-analyzer.md) | copilot | [![Video Analysis Agent](https://github.com/github/gh-aw/actions/workflows/video-analyzer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/video-analyzer.lock.yml) | - | - | +| [Weekly Editors Health Check](https://github.com/github/gh-aw/blob/main/.github/workflows/weekly-editors-health-check.md) | copilot | [![Weekly Editors Health Check](https://github.com/github/gh-aw/actions/workflows/weekly-editors-health-check.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/weekly-editors-health-check.lock.yml) | - | - | | [Weekly Issue Summary](https://github.com/github/gh-aw/blob/main/.github/workflows/weekly-issue-summary.md) | copilot | [![Weekly Issue Summary](https://github.com/github/gh-aw/actions/workflows/weekly-issue-summary.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/weekly-issue-summary.lock.yml) | `0 15 * * 1` | - | | [Weekly Safe Outputs Specification Review](https://github.com/github/gh-aw/blob/main/.github/workflows/weekly-safe-outputs-spec-review.md) | copilot | [![Weekly Safe Outputs Specification Review](https://github.com/github/gh-aw/actions/workflows/weekly-safe-outputs-spec-review.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/weekly-safe-outputs-spec-review.lock.yml) | `weekly on monday` | - | | [Weekly Workflow Analysis](https://github.com/github/gh-aw/blob/main/.github/workflows/example-workflow-analyzer.md) | claude | [![Weekly Workflow Analysis](https://github.com/github/gh-aw/actions/workflows/example-workflow-analyzer.lock.yml/badge.svg)](https://github.com/github/gh-aw/actions/workflows/example-workflow-analyzer.lock.yml) | - | - | diff --git a/docs/src/content/docs/guides/playwright-screenshots.md b/docs/src/content/docs/guides/playwright-screenshots.md new file mode 100644 index 00000000000..988ecb2a797 --- /dev/null +++ b/docs/src/content/docs/guides/playwright-screenshots.md @@ -0,0 +1,237 @@ +--- +title: Taking Website Screenshots with Playwright +description: How to take website screenshots using Playwright, upload them as assets, and post the results in GitHub issues. +sidebar: + order: 16 +--- + +This guide shows how to take screenshots of a website using Playwright, upload them to your repository as assets, and embed the URLs in a GitHub issue. + +## Overview + +The workflow follows three steps in order: + +1. Take screenshots using the Playwright MCP tool +2. Upload each screenshot using the `upload-asset` safe output +3. Create an issue with the uploaded asset URLs embedded in the body + +Asset URLs are only available after uploading, so screenshots must be captured and saved to disk before any upload step runs. + +## Workflow Configuration + +```aw wrap +--- +on: + workflow_dispatch: + issues: + types: [opened] +engine: copilot +permissions: + contents: read + issues: write +tools: + playwright: + bash: + - "mkdir *" + - "npm *" + - "kill *" + - "sleep *" + - "curl *" +safe-outputs: + upload-asset: + create-issue: + title-prefix: "[screenshot] " + labels: [screenshot, automated] +--- + +# Take Website Screenshots + +Build and serve the site locally, then take a screenshot and post the result in a GitHub issue. + +## Step 1: Create output directory + +Use the bash tool to create a directory for screenshots: + +```bash +mkdir -p /tmp/gh-aw +``` + +## Step 2: Build and serve + +```bash +npm install +npm run build +npm run preview & +``` + +Wait for the server to start on `http://localhost:4321`. Use `curl` to verify it is ready. + +## Step 3: Take screenshots + +Use the Playwright MCP tools to navigate to the site and take a screenshot: + +1. Navigate to `http://localhost:4321` +2. Take a full-page screenshot and save it to `/tmp/gh-aw/homepage.png` + +## Step 4: Upload the screenshot + +Use the `upload_asset` tool to upload `/tmp/gh-aw/homepage.png`. +Collect the returned URL. + +## Step 5: Create issue + +Create a GitHub issue titled "Website Screenshot" with the screenshot embedded: + +```markdown +### Screenshot + +![Homepage screenshot](URL_FROM_UPLOAD_ASSET) +``` +``` + +## Network Configuration + +By default, Playwright can access `localhost` and `127.0.0.1` without any additional configuration. This covers the common case of taking screenshots of a local development server started during the workflow. + +To allow access to an external site, add it to `allowed_domains` inside the `playwright:` tool configuration: + +```yaml wrap +tools: + playwright: + allowed_domains: ["defaults", "example.com", "*.example.com"] +``` + +The `allowed_domains` list accepts ecosystem bundle names (`defaults`, `github`, `node`, etc.) and individual domain patterns. Subdomains are included automatically. + +> [!TIP] +> When testing a local server started during the workflow (for example with `npm run preview`), `localhost` is included by default and no `allowed_domains` configuration is required. + +For sites outside of known ecosystems, also add the domain to the top-level `network:` block so the agent's own network traffic is allowed: + +```yaml wrap +network: + allowed: + - defaults + - "example.com" +``` + +> [!NOTE] +> The `network:` block controls outbound traffic from the agent process. `playwright.allowed_domains` controls which sites the browser is permitted to visit. Both must allow the domain when accessing an external server. + +## Asset Upload + +The `upload-asset` safe output uploads files from the workspace or `/tmp` to an orphaned git branch. The tool returns a public `raw.githubusercontent.com` URL you can embed directly in issue bodies or comments. + +Declare the safe output in frontmatter: + +```yaml wrap +safe-outputs: + upload-asset: + allowed-exts: [.png, .jpg, .jpeg] # default + max: 10 # default +``` + +In the workflow body, instruct the agent to call `upload_asset` with the file path: + +```markdown +Upload `/tmp/gh-aw/homepage.png` using the `upload_asset` tool and save the returned URL. +``` + +> [!IMPORTANT] +> Take all screenshots and save them to disk **before** calling `upload_asset`. The URL is only available after the upload completes, and you need it to embed in the issue body. + +## Creating the Issue + +After collecting the asset URLs, use `create_issue` to post the results: + +```yaml wrap +safe-outputs: + create-issue: + title-prefix: "[screenshot] " + labels: [screenshot, automated] +``` + +In the workflow body, provide the full issue template including the embedded image URL: + +```markdown +Create a GitHub issue with: + +Title: Website Screenshot - {{ site name }} + +Body: +### Screenshot + +![Screenshot]({{ URL from upload_asset }}) + +### Details +- URL: http://localhost:4321 +- Captured: {{ current date }} +``` + +## Complete Example + +The following workflow triggers on `workflow_dispatch` and on issue creation, builds and serves the site locally, takes a screenshot, and opens a report issue with the image embedded. + +```aw wrap +--- +on: + workflow_dispatch: + issues: + types: [opened] +engine: copilot +permissions: + contents: read + issues: write +tools: + playwright: + bash: + - "mkdir *" + - "npm *" + - "kill *" + - "sleep *" + - "curl *" +safe-outputs: + upload-asset: + create-issue: + title-prefix: "[screenshot] " + labels: [screenshot, automated] +--- + +# Website Screenshot Report + +Build and serve the site locally, take a screenshot, and create a GitHub issue with the results. + +## Steps + +1. Run `mkdir -p /tmp/gh-aw` using the bash tool. + +2. Build and start the local server: + ```bash + npm install && npm run build && npm run preview & + ``` + Use `curl` to verify the server is ready on `http://localhost:4321`. + +3. Use Playwright to navigate to `http://localhost:4321` and save a full-page + screenshot to `/tmp/gh-aw/homepage.png`. + +4. Upload `/tmp/gh-aw/homepage.png` using the `upload_asset` tool. + Save the returned URL as `SCREENSHOT_URL`. + +5. Create a GitHub issue using `create_issue` with the following body: + +```markdown +### Screenshot + +![Homepage](SCREENSHOT_URL) + +### Details +- URL: http://localhost:4321 +``` +``` + +## Related Documentation + +- [Tools](/gh-aw/reference/tools/#playwright-tool-playwright) - Playwright tool configuration +- [Safe Outputs](/gh-aw/reference/safe-outputs/#asset-uploads-upload-asset) - Asset upload reference +- [Network Configuration](/gh-aw/guides/network-configuration/) - Configuring network access +- [Network Access Reference](/gh-aw/reference/network/) - Complete network permissions reference