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

# CI integration with GitHub Actions

[Not sure which integration fits? Start here.](/integrations/choosing-your-integration.md)

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

Not using GitHub Actions? See [Triggering explorations from any CI](/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 targets like staging or a canary deployment.

### Start here

* [Quickstart: preview action](/integrations/github-actions/quickstart-preview-action.md)
* [Quickstart: environment action](/integrations/github-actions/quickstart-environment-action.md)
* [Choosing preview vs environment](/integrations/github-actions/choosing-preview-vs-environment.md)
* [Configuration reference](/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 target. Duku resolves the PR's preview deployment URL and explores it. | `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`](/integrations/github-actions/configuration-reference.md). |
| `environment` | Stable, long lived targets you create once in Viewport, such as staging, a production canary, or a customer specific deploy.             | `push` to a long lived branch, `schedule`, and `workflow_dispatch`                                                                                                                                                                          |

### Async by design

Both actions are async by design. A Duku exploration commonly takes 5 to 40 minutes.

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

1. Create or reference the target.
2. Resolve the URL to explore.
3. Start the exploration. The `environment` action also starts a test-case run.
4. On a native `pull_request` event, or on another trigger when you pass `repository` and `pr-number`, post one sticky `Exploration in progress` comment.
5. Exit.

When the exploration finishes, results appear in Viewport. When comment metadata is present, the same sticky comment is updated in place with run counts and the top unique errors.

{% hint style="warning" %}
Install the [Duku AI GitHub App](https://github.com/apps/duku-ai). The App posts the final PR comment update. Without it, the action still posts the running comment and exits cleanly, and the results still appear in Viewport.
{% endhint %}

### Prerequisites

1. Create a Platform API key in Viewport - **Settings → API Keys**. Store it as the repository secret `PLATFORM_API_KEY`.
2. For any run that posts a PR comment, pass `github-token: ${{ github.token }}` and set `pull-requests: write`. This includes all preview PR runs and environment runs triggered on `pull_request`.
3. Add a workflow file under `.github/workflows/`.
4. Install the [Duku AI GitHub App](https://github.com/apps/duku-ai). It is required for final PR comment updates.
5. For `environment`, create a target in Viewport first and store its ID as a repository variable like `DUKU_STAGING_TARGET_ID`.

### What to expect

GitHub Actions only starts the run. Viewport is the source of truth for final exploration and test results.

Threshold based merge gating and GitHub Check Run integration are not yet available in `0.x`. Use the PR comment or Viewport results when you decide whether to merge.

### Read next

* [Quickstart: preview action](/integrations/github-actions/quickstart-preview-action.md)
* [Quickstart: environment action](/integrations/github-actions/quickstart-environment-action.md)
* [Troubleshooting](/integrations/github-actions/troubleshooting.md)