> 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

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

[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 environments you declare once in Viewport, 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. 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. Record the build, 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 issues found.

{% hint style="warning" %}
Install the Duku AI GitHub App and link it to your Duku 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 Duku posts no PR comments or check runs until it is. The App posts the PR comments for preview runs and the final results update for environment runs. Without it, the environment action still posts its running comment, the preview action posts no comment, and results always 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. 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 Duku AI GitHub App and link it to your Duku 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. Viewport is the source of truth for final exploration and test results.

The `preview` action also gets a **GitHub check run** on the pull request, which shows the result in the PR's checks list. See GitHub check runs. The `environment` action does not post a check run.

### 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)