> 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/troubleshooting.md).

# Troubleshooting

Fix common setup and runtime issues.

Use these checks first when a workflow starts but the results are not what you expect.

### Preview run fails with "Resolving the preview URL requires a github-token"

Pass `github-token: ${{ github.token }}` in the action's `with:` block, with the read permissions shown in the preview quickstart. Or pass `exploration-url` and skip URL resolution.

The action does not receive the GitHub token automatically.

### No PR comment or check run appears

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.

For the `preview` action, the App posts both the running comment and the results. For the `environment` action, the action posts the running comment and the App posts the results.

Results still appear in Viewport even if the comment never updates.

### 403 when the environment action posts the PR comment

Grant `pull-requests: write` in the job `permissions:` block.

You can also set **Settings → Actions → General → Workflow permissions** to **Read and write**.

The `preview` action posts no comments itself, so it only needs read permissions.

### Add Preview deployments in Product settings → Environments before using the preview action

Before the first run, an org admin opens **Product settings** (the cog next to the product menu), goes to **Environments**, selects **Add environment**, sets **Type** to **Preview deployments** and selects **Create**. All pull-request previews share this one slot.

### The preview action cannot find a preview URL

Confirm that your hosting provider creates a GitHub Deployment for the pull request.

If it does not, set `preview-url-source: comments` and set `preview-comment-author-logins` to your deployment bot, such as `vercel[bot]`.

If you already know the URL, pass `exploration-url` directly.

### The workflow does not trigger

Place the workflow file under `.github/workflows/`.

Check that the `branches:` list matches the branch you actually merge into or deploy from.

### Secrets not found or pull requests from forks fail

Pull requests from forks cannot read repository secrets.

Duku previews require a pull request from a branch in the same repository.

### The exploration runs but finds nothing or cannot reach the app

If your app sits behind a firewall, WAF, or bot manager, allowlist Duku's egress IPs.

Use [Firewall & WAF Allowlisting](/integrations/firewall-and-waf-allowlisting.md) to configure the allowlist.

### Could not derive a release label

{% hint style="warning" %}
Add `actions/checkout@v4` with `fetch-depth: 0` before the Duku step so `git describe` can see your tags, or pass `release-label`.
{% endhint %}

### No release label for this run

You set `release-label-from: input` without a `release-label`. Pass `release-label`, or use another `release-label-from` source.

### Release label was not recorded: this commit already has a release

Each commit is one release, and its first name is kept. To change it, an org admin renames it in [Releases](/viewport-dashboard/releases.md) in Viewport.

### The version axis is not enabled for your organisation

[Releases](/viewport-dashboard/releases.md) and environments are switched on per organisation. Contact Duku to enable them. Until then, use `target-id`.

### The step times out waiting for the deployment

Check that the environment URL returns the pushed commit in the header named by `wait-commit-header`, on the path set by `wait-commit-path`.

### Read next

* [CI integration with GitHub Actions](/integrations/github-actions/ci-integration-with-github-actions.md)
* [Configuration reference](/integrations/github-actions/configuration-reference.md)