# GitHub Action

The GitHub Action creates or updates a simulation target from Git metadata, then optionally starts an exploration against the resolved deployment URL.

### What it does

* Creates a target for each commit
* Starts an exploration when `start-run: 'true'`
* Resolves preview URLs automatically for common providers
* Posts a PR comment as **Duku AI** when the GitHub App is installed

### Prerequisites

* A Duku API key
* Your product's subject ID
* The [Duku AI GitHub App](https://github.com/apps/duku-ai), if you want PR comments

### Setup

#### 1. Add repository secrets

In **Settings → Secrets and variables → Actions**, add:

<table><thead><tr><th width="296.333984375">Secret</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>PLATFORM_API_KEY</code></td><td>Yes</td><td>API key from Viewport</td></tr><tr><td><code>PLATFORM_SUBJECT_ID</code></td><td>Yes</td><td>Your product's subject ID</td></tr><tr><td><code>PLATFORM_API_URL</code></td><td>No</td><td>Override the default platform API URL</td></tr><tr><td><code>VERCEL_AUTOMATION_BYPASS_SECRET</code></td><td>No</td><td>Bypass secret for Vercel Deployment Protection</td></tr></tbody></table>

#### 2. Create the workflow

Create `.github/workflows/duku.yml`:

```yaml
name: Duku

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]
  push:
    branches: [main]
  workflow_dispatch: {}

jobs:
  explore:
    name: Explore with Duku
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      deployments: read
      checks: read
      statuses: read

    steps:
      - uses: actions/checkout@v4

      - name: Create Platform Target
        id: duku
        uses: Duku-AI/chrome-worker/.github/actions/platform-integration@main
        with:
          api-key: ${{ secrets.PLATFORM_API_KEY }}
          subject-id: ${{ secrets.PLATFORM_SUBJECT_ID }}
          start-run: 'true'
```

#### 3. Enable workflow permissions

In **Settings → Actions → General**, set workflow permissions to **Read and Write**.

#### 4. Trigger the workflow

Open a pull request, push to `main`, or run the workflow manually.

{% hint style="info" %}
If `start-run` is enabled for pull requests, Duku will try to resolve the preview URL before starting the run.
{% endhint %}

### Preview URL resolution

{% tabs %}
{% tab title="Auto" %}

```yaml
- name: Create Platform Target
  uses: Duku-AI/chrome-worker/.github/actions/platform-integration@main
  with:
    api-key: ${{ secrets.PLATFORM_API_KEY }}
    subject-id: ${{ secrets.PLATFORM_SUBJECT_ID }}
    start-run: 'true'
    preview-url-source: 'auto'
```

{% endtab %}

{% tab title="Vercel" %}

```yaml
- name: Create Platform Target
  uses: Duku-AI/chrome-worker/.github/actions/platform-integration@main
  with:
    api-key: ${{ secrets.PLATFORM_API_KEY }}
    subject-id: ${{ secrets.PLATFORM_SUBJECT_ID }}
    start-run: 'true'
    use-vercel-preview-url: 'true'
```

{% endtab %}

{% tab title="Comments" %}

```yaml
- name: Create Platform Target
  uses: Duku-AI/chrome-worker/.github/actions/platform-integration@main
  with:
    api-key: ${{ secrets.PLATFORM_API_KEY }}
    subject-id: ${{ secrets.PLATFORM_SUBJECT_ID }}
    start-run: 'true'
    preview-url-source: 'comments'
    preview-comment-author-logins: 'netlify[bot]'
```

{% endtab %}

{% tab title="Explicit URL" %}

```yaml
- name: Create Platform Target
  uses: Duku-AI/chrome-worker/.github/actions/platform-integration@main
  with:
    api-key: ${{ secrets.PLATFORM_API_KEY }}
    subject-id: ${{ secrets.PLATFORM_SUBJECT_ID }}
    start-run: 'true'
    exploration-url: 'https://my-preview.example.com'
```

{% endtab %}
{% endtabs %}

### Outputs

| Output           | Description                                      |
| ---------------- | ------------------------------------------------ |
| `target-id`      | ID of the created simulation target              |
| `target-name`    | Name of the created target                       |
| `target-version` | Version hash                                     |
| `run-id`         | ID of the exploration run when `start-run: true` |
| `run-status`     | Status of the exploration run                    |

Example:

```yaml
- name: Use outputs
  run: |
    echo "Target: ${{ steps.duku.outputs.target-id }}"
    echo "Run: ${{ steps.duku.outputs.run-id }}"
```

### PR comments

When exploration completes, the Duku AI GitHub App can post:

* Unique error count
* Error summaries and locations
* A link to the run in Viewport

### Troubleshooting

#### Action not found

Use this exact action path:

```yaml
uses: Duku-AI/chrome-worker/.github/actions/platform-integration@main
```

#### API connection fails

* Verify `PLATFORM_API_KEY`
* Check that the API URL is reachable from GitHub-hosted runners

#### PR comment not appearing

* Confirm the Duku AI GitHub App is installed
* Confirm the run started from a pull request context

#### Preview URL not detected

* Check whether your deploy system creates GitHub Deployments or PR comments
* Set `preview-url-source` explicitly
* Increase `preview-timeout-seconds` for slower previews


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.duku.ai/integrations/github-action.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.