Argos - Using Argos without a GitHub App

upload-screenshots-without-github-app.md

Using Argos without a GitHub App

Step-by-step guide to send screenshots to Argos without installing any GitHub App, from your CI.

This guide covers uploading images your tests already produced, not capturing them.

1. Prerequisites

1. Create a project and get the ARGOS_TOKEN:
   1. Create a team on Argos and share its name with the Argos team.
   2. The Argos team creates a project without GitHub integration and provides you the project token.
   3. Store the token as a CI secret named ARGOS_TOKEN.
2. Install the Argos CLI (@argos-ci/cli), via npx or as a dev dependency in your project. Requires Node.js 22+.

2. CI setup

On GitHub Actions, a standard actions/checkout is enough: the CLI (via @argos-ci/core) automatically detects the branch, the commit and — on a pull request — the base branch, then computes the baseline by fetching the required branches from origin. The only required variable is ARGOS_TOKEN.

Trigger the workflow on main AND on pull requests: runs on main create the reference builds, runs on PRs compare against them.

on:
  push: { branches: [main] } # reference builds
  pull_request: # compare feature branches
jobs:
  argos:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # - run: npm test        # your tests produce the images in ./screenshots
      - run: npx @argos-ci/cli upload ./screenshots
        env:
          ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}

The CLI prints the build URL at the end: ✔ Build created: https://app.argos-ci.com/…

Why trigger on main? Without a reference build on a branch's divergence commit, the feature build is of type "Orphan" and all its screenshots show up as new. Runs on main provide those references.

3. Environment variables (overrides)

On GitHub Actions, these variables are rarely needed: they force a value when auto-detection doesn't apply (other CI, upload without .git, fork PR, detached HEAD).

Variable	Purpose
ARGOS_TOKEN	Project token (40 characters, argos_…). Required, always.
ARGOS_BRANCH / ARGOS_COMMIT	Force the branch and commit if not detected (ARGOS_COMMIT = full 40-character SHA).
ARGOS_REFERENCE_BRANCH	Force the base branch. Auto-detected on PRs; otherwise falls back to the project's default base branch.
ARGOS_REFERENCE_COMMIT	Force the baseline commit, when the merge base can't be computed (fork PR, unreachable origin, upload without .git).
ARGOS_BUILD_NAME	Build name, if you run several builds per commit. (optional)
ARGOS_THRESHOLD	Diff sensitivity, 0 → 1 (default 0.5). (optional)
ARGOS_API_BASE_URL	API URL, for a self-hosted installation. (optional)

CI other than GitHub Actions: the branch and commit are still inferred from the local Git repository, but the base branch is not — make sure to set ARGOS_REFERENCE_BRANCH, and ARGOS_BRANCH / ARGOS_COMMIT if HEAD is detached.

Command options: -f, --files <globs...> (default **/*.{png,jpg,jpeg}) and -i, --ignore <globs...> to filter images.

4. Results & limitations

• Results are available in the Argos dashboard, via the build URL printed by the CLI; you approve or reject changes there.
• No status check and no PR comment on GitHub in this configuration — this is expected without an app.
• Installing a GitHub App later will enable these checks automatically, without changing anything in your CI.

5. Troubleshooting

Symptom	Solution
All screenshots show up as new (build "Orphan")	No baseline: check that Argos also runs on main (§2). As a last resort, set ARGOS_REFERENCE_COMMIT.
Build failed on a git fetch (merge-base step)	origin unreachable or branch missing on origin (e.g. fork PR). Set ARGOS_REFERENCE_COMMIT to skip the computation.
Missing Argos repository token 'ARGOS_TOKEN'	Set ARGOS_TOKEN (required). Note: fork PRs don't receive secrets.
Invalid Argos repository token (must be 40 characters)	Copy the full token (argos_ + 34 characters).
Argos requires a branch and a commit to be set	The Git context wasn't inferred (outside GitHub Actions, or detached HEAD): set ARGOS_BRANCH and ARGOS_COMMIT.
Short SHA1 is not allowed / Invalid commit	ARGOS_COMMIT must be the full SHA: git rev-parse HEAD (never --short).