ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Use an AI Agent to Screenshot a Webpage and Attach It to a GitHub Issue

Capture a webpage with an AI agent, save the screenshot, and attach it to a GitHub issue with GitHub CLI—with permissions, formats, and troubleshooting covered.

By the ScreenshotNeo team4 October 20267 min read

Use an AI agent with browser screenshot capability to capture the page and save it as a local image. Then use GitHub CLI to attach that file to an issue comment:

gh issue comment ISSUE-NUMBER --body "Screenshot of the page state:" --attach './page.png#Page screenshot'

The capture and upload are separate steps: browser automation creates the file; GitHub CLI uploads it and adds the uploaded image to the comment. The agent needs access to the page and workspace, and GitHub authentication with permission to attach files to the repository. GitHub CLI documentation says attachment requires push access. GitHub CLI: attaching files

1. Choose what part of the page to capture

Match the screenshot scope to what the issue describes:

Capture Use when
Viewport The issue concerns what a visitor sees without scrolling, including surrounding layout.
Element A specific control or component is relevant. Capture only that element when context outside it would distract.
Full page The issue spans the document or its overall layout. Full-page capture cannot be combined with an element target in the documented Playwright MCP screenshot tool.

Playwright MCP documents PNG, JPEG, and WebP output and lets you save the screenshot to a chosen filename. Playwright MCP screenshots

2. Capture and save the screenshot

Give the agent a concrete instruction: open the target URL, wait for the relevant page state, capture the appropriate scope, and save it in the repository workspace as page.png. For example:

Open https://example.com/checkout in the browser. Wait until the checkout form is visible. Capture the viewport as a PNG and save it to ./page.png. Do not submit the form or change account data.

Replace the example URL and state with the page relevant to the issue. Ensure the agent’s working directory is one the GitHub CLI can access. If the issue is about a particular component, use the browser tool’s element-target option; if the whole document is needed, use full-page mode without an element target.

For agents using OpenAI computer-use, screenshot inclusion in API output is disabled by default unless enabled. That controls whether screenshot data is returned in API output; it is separate from saving a screenshot file for a later upload. OpenAI computer-use tool

3. Attach the file to the GitHub issue

Install and authenticate GitHub CLI for the repository, then run:

gh issue comment 123 --body "Screenshot of the checkout page:" --attach './page.png#Checkout page'

Replace 123 with the issue number and update the description. The part after # supplies descriptive alt text. GitHub CLI uploads the local image and inserts its resulting URL into the comment body.

To write the comment in a file and include a Markdown image reference, create issue-comment.md:

Observed page state:

![Checkout page showing the error banner](./page.png)

Then post it with:

gh issue comment 123 --body-file issue-comment.md --attach ./page.png

When the body references the same local file passed to --attach, GitHub CLI rewrites the local Markdown reference to the uploaded asset URL. If you attach a file without referencing it in the body, the attachment is appended to the comment. GitHub CLI attachment behavior

Python agent handoff

Python does not change GitHub’s upload mechanism: let the browser-capable agent save the image, then invoke GitHub CLI. This small script posts an existing screenshot and checks the command result:

import subprocess

issue_number = "123"
image_path = "./page.png"
body = "Screenshot of the checkout page:"

subprocess.run(
    ["gh", "issue", "comment", issue_number, "--body", body,
     "--attach", f"{image_path}#Checkout page"],
    check=True,
)

Node.js agent handoff

Likewise, Node.js can run the CLI after the agent saves its screenshot. The following uses the built-in child process API:

import { execFileSync } from 'node:child_process';

execFileSync('gh', [
  'issue', 'comment', '123',
  '--body', 'Screenshot of the checkout page:',
  '--attach', './page.png#Checkout page',
], { stdio: 'inherit' });

4. Confirm the comment and image

  1. Check the CLI command completed successfully.
  2. Open the issue and confirm the comment contains the uploaded image, not a broken local path.
  3. Check that the alt text describes what the screenshot shows.
  4. Confirm the image shows the relevant state and does not expose secrets, personal data, tokens, or unrelated private content.

For a manual fallback, GitHub’s issue comment box accepts drag-and-drop or file-picker uploads. The file uploads immediately and the text field is populated with an anonymized URL. GitHub Docs: attaching files

5. Access, visibility, and upload limits

  • Repository permission: GitHub CLI requires push access to attach files. Browser automation or a screenshot tool does not grant GitHub permission. Confirm CLI authentication and the account’s repository access.
  • Visibility: GitHub’s guide says files uploaded to public repositories can be accessed without authentication. Files in private or internal repositories are viewable only by people with repository access. Treat screenshots on public issues as public material.
  • File size: GitHub’s cited attachment guide lists a 10 MB limit for images and GIFs and 25 MB for other files. These limits can change, so check the current guide if an upload is rejected.
  • Format: Playwright MCP documents PNG, JPEG, and WebP screenshot output. Use a format supported by the capture tool and accepted by GitHub’s current attachment flow.

6. Choosing an upload route

Route Best for Tradeoff
GitHub CLI --attach Repeatable agent or developer workflows and inline issue comments. Requires CLI setup, repository authentication, and push access.
GitHub issue web form One-off manual uploads or a browser-only fallback. Requires interactive operation of the GitHub UI.
Workflow artifact Making a generated screenshot retrievable by workflow users. An artifact is a downloadable workflow output, not an inline issue attachment. GitHub Agentic Workflows documents safe output paths, upload limits, and retention settings for artifact publishing. GitHub Agentic Workflows: Playwright

7. Troubleshooting

Symptom Likely cause Fix
gh issue comment cannot find the issue Wrong issue number, repository context, or host. Run the command from the intended repository, verify the issue number, and check the configured GitHub host.
Authentication or permission error CLI is unauthenticated, authenticated as the wrong account, or lacks push access. Authenticate the intended account and confirm it has the required repository permission. The agent’s browser session alone is not sufficient for CLI upload.
Attachment path not found The agent saved the image elsewhere, used a different filename, or the CLI ran from another directory. Save to a shared workspace path and pass the exact path to --attach. Check that the file exists before posting.
Image missing or local path remains in comment The file was not attached, or the Markdown reference does not match the attached local path. Attach the same path referenced in the body, then inspect the resulting comment.
Upload rejected The file exceeds the current size limit or its format is not accepted. Check GitHub’s current attachment rules; capture a smaller scope or use a supported image format.
Screenshot is blank or shows the wrong state The page had not reached the target state, navigation was incomplete, or the capture scope was wrong. Wait for a visible selector or page state before capture, verify the URL, and choose viewport, element, or full page to match the issue.
Full-page and target selector conflict The documented Playwright MCP screenshot tool does not combine full-page mode with an element target. Choose full-page capture or element capture for that run.
Screenshot output is not returned by an OpenAI computer-use agent Screenshot inclusion in API output is disabled by default. Enable screenshot inclusion if the agent must return screenshot data; separately ensure the workflow saves a file for upload.

8. Reliability, performance, and cost

Capture only after the page reaches the state under discussion. A specific selector or deliberate wait can reduce screenshots of loading placeholders; for long pages, full-page captures may produce larger files and take longer to inspect or upload. Keep the image limited to the relevant context and check the saved file before posting.

GitHub CLI attachment is a separate authenticated network operation after capture. If capture succeeds but upload fails, keep the local file and retry the upload once permissions and connectivity are corrected. This workflow has no universal cost or timing guarantee: the browser runtime, agent, network, and any screenshot service determine those details. Do not put credentials or private page data in a screenshot that will be attached to a public issue.

9. Or skip the browser setup

For a direct screenshot API call, request the image from ScreenshotNeo and save the response. See the ScreenshotNeo API documentation for parameters and configuration. Then attach the saved file using the GitHub CLI command above.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo, then sign up for 1,000 free screenshots a month with no card.

FAQ

Can an AI agent attach the screenshot without GitHub credentials?

No. The upload step needs GitHub authentication and sufficient repository permission. Browser access for capturing a page does not automatically authorize an issue comment.

Should I attach a screenshot or upload it as a workflow artifact?

Attach it when readers should see it inline in the issue conversation. Use a workflow artifact when users need to retrieve a generated file from a workflow run.

Does capturing a screenshot automatically create an issue comment?

No. The capture tool produces the image; a separate GitHub CLI or web upload action adds it to the issue.

Keep reading