> For the complete documentation index, see [llms.txt](https://docs.getantidote.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/ci-integration-with-github-actions.md).

# CI integration with GitHub Actions

Start Antidote from pull requests, deploys, and scheduled workflows.

[Not sure which integration fits? Start here.](https://docs.getantidote.com/welcome-to-antidote/integrations/choosing-your-integration.md)

Use Antidote's GitHub Actions to start explorations from your CI pipeline.

Not using GitHub Actions? See [Triggering explorations from any CI](https://docs.getantidote.com/welcome-to-antidote/integrations/triggering-explorations-from-any-ci.md) to call the Platform API directly from any pipeline.

Use `preview` for short lived pull request previews. Use `environment` for stable environments like staging or a canary deployment.

### Start here

* [Quickstart: preview action](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/quickstart-preview-action.md)
* [Quickstart: environment action](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/quickstart-environment-action.md)
* [Choosing preview vs environment](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/choosing-preview-vs-environment.md)
* [Configuration reference](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/configuration-reference.md)

### Which action to use

| Action        | Use it for                                                                                                                                                                          | Trigger events                                                                                                                                                                                                                                                                              |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `preview`     | Per pull request previews, where each PR gets its own short lived deployment. Antidote resolves the PR's preview deployment URL and tests what the pull request changes there.      | `pull_request` as the primary trigger. It also runs on `push` and `workflow_dispatch`. On those triggers, it only posts a PR comment when you pass [`repository` and `pr-number`](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/configuration-reference.md). |
| `environment` | Stable, long lived environments you declare once in the Antidote dashboard, such as staging, a production canary, or a customer specific deploy. Each run is recorded as a release. | `push` to a long lived branch, `schedule`, `workflow_dispatch`, and `pull_request` into a protected branch                                                                                                                                                                                  |

### Async by design

Both actions are async by design. The workflow starts the run and does not wait. Results appear on the pull request and in the Antidote dashboard.

The workflow starts the exploration and exits within seconds. This keeps your runner free and avoids spending Actions minutes while Antidote explores the app.

1. Record the build: a preview build for `preview`, or a release on the environment for `environment`.
2. Resolve the URL to explore.
3. Start an Antidote run. On a pull request, Antidote tests what the pull request changes. On `push`, `schedule` and `workflow_dispatch`, the `environment` action has Antidote run your flows on the new release and queue an exploration of it.
4. On a native `pull_request` event, or on another trigger when you pass `repository` and `pr-number`, the `environment` action posts one sticky `Exploration in progress` comment.
5. Exit.

Results appear in the Antidote dashboard. On a pull request, the Antidote GitHub App posts one comment per product listing what Antidote tried and whether each worked, updates it in place, and concludes the `Duku Exploration (<product name>)` check run. Once that comment is final, the `environment` action's running comment links to it.

{% hint style="warning" %}
Install the Antidote GitHub App and link it to your Antidote organisation. An org admin opens **Settings → Integrations**, selects **+ Connect** under **Source control & CI/CD**, chooses **GitHub** and selects **Install on GitHub**. If the App is already installed on your GitHub organisation, select **Link existing install** instead. An App installed straight from GitHub is not linked, and Antidote posts no PR comments or check runs until it is. Antidote reads each pull request through the App, and the App posts the PR comment and check run for both actions. Without it, Antidote does not test the pull request: the preview action posts no comment, the environment action's running comment stays as posted, and the step logs what to fix.
{% endhint %}

### Prerequisites

1. Create a Platform API key in **Settings → API keys**. Store it as the repository secret `PLATFORM_API_KEY`.
2. Pass `github-token: ${{ github.token }}` on every preview PR run (it finds the preview URL) and on environment runs. Environment runs on `pull_request` also need `pull-requests: write` for their running comment.
3. Add a workflow file under `.github/workflows/`.
4. Install the Antidote GitHub App and link it to your Antidote organisation from **Settings → Integrations** - see the hint above. It is required for PR comments and check runs.
5. For `environment`, declare the environment in **Product settings → Environments** and store the product ID as the repository variable `PLATFORM_PRODUCT_ID`.
6. For `preview`, add **Preview deployments** in **Product settings → Environments** - see Quickstart: preview action.

### What to expect

GitHub Actions only starts the run. The Antidote dashboard is the source of truth for results.

On a pull request, both actions get a **GitHub check run**, `Duku Exploration (<product name>)`, which shows the result in the PR's checks list. See GitHub check runs. Runs on `push`, `schedule` and `workflow_dispatch` post no check run.

### Read next

* [Quickstart: preview action](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/quickstart-preview-action.md)
* [Quickstart: environment action](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/quickstart-environment-action.md)
* [Troubleshooting](https://docs.getantidote.com/welcome-to-antidote/integrations/github-actions/troubleshooting.md)
