# 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** (or a [context](https://circleci.com/docs/contexts/)) named `SHIPLIGHT_API_TOKEN`.
- One-time: connect the repository in the CircleCI app (**Projects → Set Up Project**) so CircleCI reads your config.

## Pipeline

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

```yaml
version: 2.1

jobs:
  e2e:
    docker:
      - image: cimg/node:20.11-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
```

## 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).
- 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, the self-healing action cache, automatic LLM 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)