CI/CD integration

You can trigger FreshShots workflows automatically during your CI/CD pipelines — for example, after deployments, before releases, or to keep screenshots fresh after UI changes.

This guide walks through how to integrate the FreshShots API into popular CI/CD systems.

🔧 API Endpoint Overview

To trigger a screenshot capture workflow:

curl -X POST https://api.freshshots.io/v1/run/{workflow_id} \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-server.com/webhook"}'

Replace {workflow_id} with your actual workflow ID
Replace YOUR_API_KEY with your secret key (use pipeline secrets!)
webhook_url is optional

🚀 GitHub Actions

Add a step after deployment or on merge to main:

name: Trigger FreshShots

on:
    push:
        branches:
            - main

jobs:
    run-freshshots:
        runs-on: ubuntu-latest
        steps:
            - name: Trigger Screenshot Workflow
              run: |
                  curl -X POST https://api.freshshots.io/v1/run/23 \
                    -H "x-api-key: ${{ secrets.FRESHSHOTS_API_KEY }}" \
                    -H "Content-Type: application/json"

🧠 Tip: Store your FreshShots API key under Repository Settings → Secrets → Actions

🦊 GitLab CI/CD

In .gitlab-ci.yml:

freshshots:
  stage: post-deploy
  script:
    - curl -X POST https://api.freshshots.io/v1/run/23 \
        -H "x-api-key: $FRESHSHOTS_API_KEY" \
        -H "Content-Type: application/json"
  only:
    - main

Add your API key to Settings → CI/CD → Variables (FRESHSHOTS_API_KEY).

🧵 Bitbucket Pipelines

In bitbucket-pipelines.yml:

pipelines:
  default:
    - step:
        name: Trigger FreshShots
        script:
          - curl -X POST https://api.freshshots.io/v1/run/23 \
              -H "x-api-key: $FRESHSHOTS_API_KEY" \
              -H "Content-Type: application/json"

Store your key under Repository Settings → Repository Variables

⚙️ CircleCI

In .circleci/config.yml:

jobs:
    run-freshshots:
        docker:
            - image: cimg/base:stable
        steps:
            - run:
                  name: Trigger FreshShots Workflow
                  command: |
                      curl -X POST https://api.freshshots.io/v1/run/23 \
                        -H "x-api-key: $FRESHSHOTS_API_KEY" \
                        -H "Content-Type: application/json"

workflows:
    version: 2
    post-deploy:
        jobs:
            - run-freshshots

Set FRESHSHOTS_API_KEY in Project Settings → Environment Variables

🧬 Others (Vercel, Netlify, Jenkins, etc.)

As long as your pipeline supports running shell commands or curl, you can call the API like this:

curl -X POST https://api.freshshots.io/v1/run/23 \
  -H "x-api-key: $FRESHSHOTS_API_KEY" \
  -H "Content-Type: application/json"

For Vercel, use a Webhook → Serverless Function to call FreshShots post-deploy.

✅ Best Practices

💾 Store API keys in secret environments or CI/CD variables
🧪 Trigger only on relevant branches (e.g. main, release/*)
🚦 Use webhooks to confirm screenshots completed successfully
📂 Integrate with your docs or dashboard to display the latest screenshots

📬 Webhook Integration

FreshShots can notify you when screenshots are done. Include webhook_url in the request body:

{
	"webhook_url": "https://your-ci-system.com/webhook"
}

Example response payload:

{
	"workflow_id": "23",
	"status": "completed",
	"screenshots": [
		{
			"id": "abc123",
			"cdn_url": "https://cdn.freshshots.io/screenshots/..."
		}
	]
}

Need help wiring this into your CI/CD pipeline? Email us at [email protected] — we’re happy to help.

Documentation