GitHub Action (Pilot)

Required secrets

• SCREENSHOT_API_KEY → your pilot API key

Copy/paste workflow (pilot)

This workflow calls the API directly and uploads screenshots as build artifacts.

1) Add a secret in your repo

• SCREENSHOT_API_KEY → your pilot API key

Note: The API URL (https://snap.i2dev.com) is public, so we hardcode it in the example below. If you later need a dedicated deployment, contact Rana.

2) Add this workflow

Create .github/workflows/screenshots.yml in your repo:

name: Screenshots

on:
  pull_request:

jobs:
  screenshots:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Request screenshots
        env:
          SCREENSHOT_API_URL: https://snap.i2dev.com
          SCREENSHOT_API_KEY: ${{ secrets.SCREENSHOT_API_KEY }}
        run: |
          set -euo pipefail

          mkdir -p screenshots

          # Add the URLs you want to capture (one per line)
          cat <<'URLS' > urls.txt
          https://example.com
          URLS

          i=0
          while read -r URL; do
            [ -z "$URL" ] && continue
            i=$((i+1))

            echo "Capturing: $URL"

            curl -sS -X POST "$SCREENSHOT_API_URL/v1/screenshots" \
              -H "Authorization: Bearer $SCREENSHOT_API_KEY" \
              -H "Content-Type: application/json" \
              -d "{\"url\":\"$URL\"}" \
              > "screenshots/resp-$i.json"

            IMAGE_URL=$(jq -r '.imageUrl' "screenshots/resp-$i.json")
            if [ -z "$IMAGE_URL" ] || [ "$IMAGE_URL" = "null" ]; then
              echo "No imageUrl returned:" && cat "screenshots/resp-$i.json" >&2
              exit 1
            fi

            curl -sS "$IMAGE_URL" -o "screenshots/screenshot-$i.png"
          done < urls.txt

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: screenshots/

Reusable Action (Alternative)

Instead of the curl-based workflow above, you can use the reusable action with built-in artifact upload:

name: Screenshots

on:
  pull_request:

jobs:
  screenshot:
    runs-on: ubuntu-latest
    steps:
      - name: Capture screenshot
        uses: ranacseruet/screenshot-api/github-action@main
        with:
          api_url: https://snap.i2dev.com
          api_key: ${{ secrets.SCREENSHOT_API_KEY }}
          url: https://example.com
          upload_artifact: true
          artifact_name: my-screenshot

Action Inputs

Action Outputs

Notes

• The API is synchronous; very large/slow pages may timeout.
• If you have preview URLs, build them using ${{ github.event.pull_request.number }}.

Troubleshooting

Preview not ready

If your preview deployment isn't ready when the Action runs, add a wait step:

- name: Wait for preview
  run: |
    for i in {1..30}; do
      curl -sf "https://preview-${{ github.event.pull_request.number }}.example.com" && exit 0
      sleep 10
    done
    exit 1

- name: Request screenshot(s)
  run: |
    # call https://snap.i2dev.com/v1/screenshots and upload artifacts
  # ...

Authentication errors

Make sure SCREENSHOT_API_KEY is set in your repository secrets (Settings → Secrets → Actions).