> 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/quickstart-preview-action.md).

# Quickstart: preview action

{% hint style="warning" %}
Install the [Duku AI GitHub App](https://github.com/apps/duku-ai) on the repository. The App posts the final PR comment update. Without it, results still appear in Viewport, but the PR comment does not update with final results.
{% endhint %}

Use this workflow when each pull request gets its own preview deployment.

{% stepper %}
{% step %}

### 1. Add the required repository secret and variable

Create `PLATFORM_API_KEY` in Viewport - **Settings → API Keys**.

Add `PLATFORM_PRODUCT_ID` as a repository variable. It is not a secret.
{% endstep %}

{% step %}

### 2. Create the workflow file

Copy this file into `.github/workflows/duku-preview.yml`:

```yaml
name: Duku preview

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]

concurrency:
  group: duku-preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  preview:
    name: Duku preview
    runs-on: ubuntu-latest
    # The action exits in seconds; this cap only guards against network hangs.
    timeout-minutes: 5
    permissions:
      contents: read
      pull-requests: write   # required to post the sticky "running" PR comment
      deployments: read      # required for preview URL resolution
      checks: read           # for preview URL resolution
      statuses: read         # for preview URL resolution
    steps:
      - uses: actions/checkout@v4
      - name: Duku preview
        id: preview
        uses: duku-ai/actions/preview@preview/v0.2.0
        with:
          api-key: ${{ secrets.PLATFORM_API_KEY }}
          product-id: ${{ vars.PLATFORM_PRODUCT_ID }}
          # Optional: bypass Vercel Deployment Protection on protected previews.
          # vercel-automation-bypass-secret: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
```

{% endstep %}

{% step %}

### 3. Update the workflow values

* `branches: [main]` should match the branch you merge into.
* `api-key` reads the repository secret `PLATFORM_API_KEY`.
* `product-id` reads the repository variable `PLATFORM_PRODUCT_ID`.

`pull-requests: write` lets the action post the sticky running comment.

`deployments: read`, `checks: read`, and `statuses: read` let the action resolve the preview URL.
{% endstep %}

{% step %}

### 4. Open or update a pull request

The workflow resolves the preview URL, starts the exploration, and exits within seconds.

The `concurrency` block cancels superseded runs for the same pull request.

Results appear in Viewport. The GitHub App updates the same PR comment with final results.
{% endstep %}
{% endstepper %}

PRs opened from forks cannot read repository secrets. Duku previews require a PR from a branch in the same repository.

### Preview URL resolution

On a pull request, the `preview` action figures out which deployed URL to explore.

With `preview-url-source: auto`, it checks the PR's GitHub Deployments first. It can then fall back to pull request comments from a deployment bot if you configure one.

You can force a single source. You can also set `exploration-url` to skip resolution entirely.

#### Example: resolve the URL from Vercel comments

```yaml
- uses: duku-ai/actions/preview@preview/v0.2.0
  with:
    api-key: ${{ secrets.PLATFORM_API_KEY }}
    product-id: ${{ vars.PLATFORM_PRODUCT_ID }}
    preview-url-source: 'comments'
    preview-comment-author-logins: 'vercel[bot]'
```

`auto` is usually the right choice. Use `comments` when your deployment provider does not publish a usable GitHub Deployment.

### Read next

* [Choosing preview vs environment](/integrations/github-actions/choosing-preview-vs-environment.md)
* [Configuration reference](/integrations/github-actions/configuration-reference.md)
* [Troubleshooting](/integrations/github-actions/troubleshooting.md)