<!-- Markdown twin of https://pixelvault.dev/docs/guides/ci-screenshots/ -->

# Host CI screenshots

**Goal:** when an end-to-end test fails, reviewers see the screenshot in the pull request instead of downloading a zipped artifact. Screenshots stay private behind signed URLs, and each run is one collection you can clean up.

## GitHub Actions

The [PixelVault screenshots action](https://github.com/marketplace/actions/pixelvault-upload-screenshots) wraps the batch endpoint: on a failed run it uploads your Playwright / visual-regression screenshots and posts a sticky comment to the pull request. Add your key as the repository secret `PIXELVAULT_API_KEY`, then:

```
# .github/workflows/e2e.yml
name: e2e
on: pull_request

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write  # for the sticky PR comment
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test

      - name: Host failure screenshots
        if: failure()
        uses: pixelvault-dev/screenshots-action@v1
        with:
          api-key: ${{ secrets.PIXELVAULT_API_KEY }}
          path: test-results
          pattern: "*-diff.png"
          visibility: private
```

Re-running the job updates the same comment in place (the collection is idempotent by run), so a flaky retry doesn't stack comments. With `visibility: private` every screenshot is served behind a signed URL: the link in the PR works for reviewers, but strip the signature and the CDN returns `403`.

## Any other CI

The action is a thin wrapper over [`POST /v1/images/batch`](/docs/api/images/#batch_upload), so GitLab CI, CircleCI, Jenkins, or a local run work the same way: post a run's screenshots (up to 50 per request) as one batch and get back a signed URL per image.

Upload a run

ShellNode.js

```
#!/usr/bin/env bash
# upload-screenshots.sh: host every PNG under test-results as one private collection.
set -euo pipefail

RUN="${CI_PIPELINE_ID:-local-$(date +%s)}"
ITEMS=$(find test-results -name '*.png' | head -n 50 | while read -r f; do
  jq -n --arg data "$(base64 < "$f" | tr -d '\n')" --arg name "$(basename "$f")" \
    '{data: $data, filename: $name}'
done | jq -s .)

jq -n --arg run "$RUN" --argjson images "$ITEMS" \
  '{collection: {type: "ci_build", name: $run, visibility: "private"}, images: $images}' |
curl -sS -X POST https://api.pixelvault.dev/v1/images/batch \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- |
jq -r '.data.items[] | if .ok then "\(.filename): \(.url)" else "\(.filename): FAILED \(.error)" end'
```

Each item reports `ok` independently, so one oversized file doesn't fail the run. Signed links last 7 days by default; set `sign_expires_in` to change that. Private assets count toward the free plan's 100-asset cap, so close old runs.

## Clean up old runs

Close a run's collection when the pull request merges and its screenshots are removed at the next sweep, or set `expires_in` on the batch to delete them automatically:

```
curl -X POST https://api.pixelvault.dev/v1/collections/col_abc123/close \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
```

## Next steps

-   [Full walkthrough](/blog/host-playwright-ci-screenshots/) with a PR comment example.
-   [Private media & signed URLs](/docs/private-media/).
-   [Compress images in CI](/docs/cli/#optimize) with `pixelvault-cli optimize`.
