# CircleCI

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

Run your Shiplight E2E tests in CircleCI and upload the results to [Shiplight Cloud](https://app.shiplight.ai). CircleCI uses the same `shiplight` CLI as every other provider — only the pipeline syntax differs.

## Before you start

- A scaffolded Shiplight test project (`/shiplight init`). See the [CI/CD overview](/local/ci) for how the pieces fit together.
- An org API token from [app.shiplight.ai/api-tokens](https://app.shiplight.ai/api-tokens), stored as a project **environment variable** named `SHIPLIGHT_API_TOKEN`.
- One-time: connect the repository in CircleCI. For a GitHub repository, install and authorize the CircleCI GitHub App for that repository.

## Pipeline

Create `.circleci/config.yml` at your repository root:

```yaml
version: 2.1

jobs:
  e2e:
    docker:
      - image: cimg/node:22.14-browsers # -browsers variant ships the system libs Chromium needs
    environment:
      SHIPLIGHT_REPORT_TO_CLOUD: "1"
      # SHIPLIGHT_API_TOKEN comes from a project env var / context.
    steps:
      - checkout
      - run: npm install
      - run: npx playwright install chromium
      - run: npx shiplight test
      - run:
          name: Upload results to Shiplight
          command: npx shiplight report
          when: always # upload even when tests fail

workflows:
  e2e:
    jobs:
      - e2e
```

## Connect and run the pipeline

After committing `.circleci/config.yml`:

1. Create or select the project in CircleCI and connect your repository. For GitHub, use the CircleCI GitHub App integration.
2. Open **Project Settings → Project Setup** and add a pipeline with:
   - **Config source:** your repository
   - **Config filepath:** `.circleci/config.yml`
   - **Checkout source:** your repository
3. Save the pipeline.
4. Open **Project Settings → Environment Variables** and add `SHIPLIGHT_API_TOKEN` with your Shiplight org API token as its value.
5. Push a commit or trigger the pipeline from CircleCI.

## Notes

- `SHIPLIGHT_API_TOKEN` and `SHIPLIGHT_REPORT_TO_CLOUD=1` are required on every non-Shiplight runner — they are provided automatically only on [Shiplight-hosted GitHub runners](/local/ci/github-actions).
- With `SHIPLIGHT_API_TOKEN` set, AI-powered actions run through the Shiplight LLM proxy, and healed locators persist to the Shiplight Cloud action cache so later runs can reuse them.
- The `cimg/node:*-browsers` image bundles the system libraries Chromium needs, so a plain `npx playwright install chromium` is enough. On a non-browser image, use `--with-deps`.
- `when: always` on the report step is what makes the upload survive a red run.
- **Not available on CircleCI:** Shiplight-hosted runners, automatically provisioned credentials, and [auto-triage](/local/ci/github-actions#auto-triage-ci-failures-optional) — those are GitHub Actions only.
- Project in a subdirectory (e.g. `tests/e2e`)? Add `working_directory: ~/project/tests/e2e` to the job, or `cd` into it before each command.

## Related

- [CI/CD overview](/local/ci) · [Custom setups](/local/ci/custom) · [CLI Reference](/local/cli-reference)