Run on a preview deployment

In a workflow triggered by deployment_status, the Snapvisor SDK takes the branch from deployment.environment (the name of the deployment environment) instead of from a git branch, so the build is uploaded under a branch named after the environment. The commit comes from GITHUB_SHA, which for this event is the deployed commit. The event carries no pull request, so the build is not linked to one automatically. With tokenless authentication the upload can also be refused with GitHub Actions workflow run does not match branch. Setting the branch yourself and authenticating with a project token avoids these problems.

Workflow

name: Visual tests on preview

on: deployment_status

jobs:
  visual-tests:
    # Only run once the deployment is live.
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.deployment.sha }}
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx playwright test
        env:
          BASE_URL: ${{ github.event.deployment_status.environment_url }}
          ARGOS_BRANCH: ${{ github.event.deployment.ref }}
          ARGOS_COMMIT: ${{ github.event.deployment.sha }}
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

Point your Playwright baseURL at process.env.BASE_URL and upload with the Snapvisor integration described in SDKs. Cypress works the same way: set the same environment variables on the cypress run step.

What each setting does

• ARGOS_BRANCH and ARGOS_COMMIT override what the SDK detects from the CI environment. deployment.ref is the branch or tag that was deployed and deployment.sha is its commit. If a deployment was created from a bare commit, ref can be the SHA itself; set a fixed branch name in that case.
• ARGOS_TOKEN is the project token from your project settings, stored as a repository secret. Use it here. When ARGOS_TOKEN is set the SDK uses it before OIDC or tokenless authentication. Tokenless authentication compares the uploaded branch and commit with the GitHub workflow run and rejects a branch that does not match; a project token skips that check.
• environment_url is the URL of the deployed preview that your tests visit.
• The success guard skips the earlier statuses GitHub sends while the deploy is still running. GitHub does not start a workflow at all when the status is inactive.

Vercel

Vercel sends deployment_status events to GitHub by default. If the workflow never starts, check that the deployment_status Events toggle is on in your project's Git settings. Print ${{ toJSON(github.event.deployment) }} once to see which environment and ref your project reports, and set ARGOS_BRANCH to your default branch for production deployments so the build updates your baseline.

Vercel also recommends its repository_dispatch event (vercel.deployment.success) over deployment_status. The Snapvisor SDK handles that event natively, reading the branch and commit from the Vercel payload, so you do not need to set ARGOS_BRANCH or ARGOS_COMMIT there.

Related

• CI integration
• GitHub tokenless authentication
• GitHub Actions OIDC authentication
• Access tokens