> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qawolf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate with CircleCI

> Automatically trigger test runs when you deploy code from your repository.

<Note>
  This page describes [legacy triggers](/legacy-triggers/overview). See [Triggers](/triggers/overview) for the current documentation.
</Note>

If your deployments run through CircleCI, add a job that notifies QA Wolf once a deploy succeeds. Contact your QA Wolf representative before setting this up.

## Requirements

* Access to a QA Wolf workspace with a deployment trigger configured for your environment
* Admin access to your CircleCI project

## How to connect QA Wolf to CircleCI

<Steps>
  <Step title="Add the QAWOLF_API_KEY variable">
    Add `QAWOLF_API_KEY` as an environment variable in your CircleCI project under **Project Settings → Environment Variables**.
  </Step>

  <Step title="Add the notify script to your repository">
    Create `.circleci/notifyQaWolf.mjs` in the repository that corresponds to the deployments QA Wolf will be testing.

    ```javascript expandable theme={null}
    import assert from "assert";
    import { makeQaWolfSdk } from "https://esm.sh/@qawolf/ci-sdk@0.23.0";

    const apiKey = process.env.QAWOLF_API_KEY;
    assert(apiKey, "QAWOLF_API_KEY is required");

    const sha = process.env.CIRCLE_SHA1;
    assert(sha, "CIRCLE_SHA1 is required");

    const branch = process.env.CIRCLE_BRANCH;
    assert(branch, "CIRCLE_BRANCH is required");

    const deployConfig = {
      branch,
      // Required only if the target trigger requires matching a deployment type
      deploymentType: "staging", // e.g., "production", "staging", "qa"
      // Optional: Include deployment URL to override URL environment variable for the run
      deploymentUrl: undefined,
      hostingService: "GitHub", // Set to where your repo is hosted, e.g. "GitHub" or "GitLab"
      // Optional: Include pull request number for PR testing
      // pullRequestNumber: 123,
      // Recommended: Include repository information
      repository: {
        name: "your-repo-name",
        owner: "your-org-name",
      },
      sha,
    };

    const { attemptNotifyDeploy } = makeQaWolfSdk({ apiKey });

    const result = await attemptNotifyDeploy(deployConfig);
    if (result.outcome !== "success") {
      // Fail the job.
      throw Error(`Failed to notify QAWolf: ${JSON.stringify(result)}`);
    }

    // result.runId can be output from the job to be used in a CI-greenlight job.
    ```

    Replace `deploymentType` with the value your QA Wolf representative provides, and `name` and `owner` with your repository details. Set `hostingService` to where your code is hosted, not where your pipeline runs.
  </Step>

  <Step title="Add the notify job to your CircleCI config">
    Add the `notify-qa-wolf` job to your `.circleci/config.yml`, placed in your workflow after your deploy job.

    ```yaml theme={null}
    version: 2.1

    orbs:
      node: circleci/node@7.0.0

    jobs:
      # build: TODO
      # deploy: TODO
      notify-qa-wolf:
        executor: node/default
        steps:
          - checkout
          - run: node --version
          - run: node --experimental-network-imports .circleci/notifyQaWolf.mjs

    workflows:
      build-deploy-test-workflow:
        jobs:
          # - build
          # - deploy
          - notify-qa-wolf
    ```
  </Step>

  <Step title="Verify the integration">
    Push a commit and wait for your CircleCI pipeline to complete. Confirm a new run appears in QA Wolf under the expected environment.
  </Step>
</Steps>

## Related

* [QA Wolf CI SDK](/legacy-triggers/ci-sdk-integration)