Quickstart: preview action

Start Duku automatically for pull request previews.

Install the Duku AI GitHub App 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.

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

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.

2. Create the workflow file

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

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.1.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 }}

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.

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.

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

- uses: duku-ai/actions/preview@preview/v0.1.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.

1. Add the required repository secret and variable

2. Create the workflow file

3. Update the workflow values

4. Open or update a pull request

Preview URL resolution

Example: resolve the URL from Vercel comments

Read next