> 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/configuration-reference.md). # Configuration reference Review inputs, outputs, secrets, and versioning. Use this reference when you need to tune URL resolution, read action outputs, or pin a specific release. ### `preview` inputs | Name | Required | Default | Description | | -------------------------------------- | -------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api-key` | Yes | `-` | Platform API key. Generate in Viewport - **Settings → API Keys**. | | `product-id` | Yes | `-` | Duku product ID from Viewport - **Products**. | | `api-url` | No | `https://platform.duku.ai/graphql` | Platform API endpoint. | | `auth-url` | No | *derived from api-url* | Authentication server URL. | | `run-exploration` | No | `true` | Start an exploration after recording the build. | | `start-run` | No | - | Deprecated alias for `run-exploration`. | | `vercel-automation-bypass-secret` | No | *(empty)* | Bypass Vercel Deployment Protection on protected previews. | | `exploration-url` | No | *product base URL* | Explore this URL instead of resolving one. | | `release-label` | No | *(empty)* | Human-readable release name for this build, e.g. `1.4.2`. Recorded alongside the commit SHA. | | `credential-set` | No | *(empty)* | The credential set to log in with, by name or ID, from this product's sets. An unknown set fails the step rather than using the default. Empty uses the product's default login. | | `preview-url-source` | No | `auto` | How to resolve the preview URL on a PR: `auto`, `deployments`, `checks`, `statuses`, `comments`, or `none`. `auto` tries GitHub Deployments, then Checks, then Statuses for the PR's head commit. Set `comments` to read the URL from a deployment bot's PR comment. | | `preview-timeout-seconds` | No | `60` | How long to wait for a preview URL to appear in a PR comment. Used only with `preview-url-source: comments`. | | `preview-poll-interval-seconds` | No | `5` | How often to poll for the preview URL. Used only with `preview-url-source: comments`. | | `wait-for-target-seconds` | No | *(empty)* | Give the preview URL this long to start serving before the run begins. Empty starts immediately. Duku caps the wait and logs a warning if it shortens your request. | | `preview-deployment-environment-regex` | No | *(empty)* | Regex matching the GitHub Deployment environment name. Defaults to a conservative `preview\|review\|staging\|pr`. | | `preview-check-name-regex` | No | *(empty)* | Regex matching a Check Run name. Skipped in `auto` if empty. | | `preview-status-context-regex` | No | *(empty)* | Regex matching a commit status context. Skipped in `auto` if empty. | | `preview-comment-author-logins` | No | *(empty)* | Comma separated bot or user logins whose PR comments may carry the preview URL, for example `vercel[bot],netlify[bot]`. | | `preview-url-regex` | No | *(empty)* | Regex to extract the preview URL from a provider comment. | | `github-installation-id` | No | `-` | Duku AI GitHub App installation ID. Normally auto discovered when the App is installed. Only set this for a custom installation map. | | `repository` | No | `-` | Repository in `owner/repo` format. Set this together with `pr-number` to attach PR metadata and post the sticky PR comment on non `pull_request` triggers. | | `pr-number` | No | `-` | Pull request number. Set this together with `repository` to attach PR metadata and post the sticky PR comment on non `pull_request` triggers. | | `github-token` | No | *(empty)* | Used to resolve the preview URL from GitHub. Not needed when `exploration-url` is set. Pass `${{ github.token }}` explicitly; GitHub does not set it automatically. The Duku AI GitHub App posts the preview PR comment. | ### `preview` outputs | Name | Description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `target-id` | ID of the created target. | | `target-name` | Name of the created target. | | `target-version` | Version of the created target. | | `run-id` | ID of the started exploration. On PR events, this is the same value as `exploration-batch-id`. | | `run-status` | Kickoff status: `triggered` on pull requests. On other events, the run's status as Duku reports it. | | `preview-url-source` | Which resolver found the URL: `deployments`, `checks`, `statuses`, `comments`, or `override` when `exploration-url` was set. | | `exploration-batch-id` | ID of the exploration on PR events. | | `comment-id` | Deprecated. Always empty on PR events. The status comment is now posted server-side by the Duku AI GitHub App. | ### `environment` inputs | Name | Required | Default | Description | | -------------------------------------- | -------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api-key` | Yes | - | Platform API key. Generate in Viewport - **Settings → API Keys**. | | `product-id` | No | *(empty)* | Duku product ID. Use with `environment` to record each commit as a release on that environment. | | `environment` | No | *the product's default environment* | Name of an environment declared in **Product settings → Environments**, e.g. `staging`. | | `release-label` | No | *(empty)* | Release name for this build, e.g. `1.4.2`. Overrides `release-label-from`. | | `release-label-from` | No | `git-describe` | Where the release name comes from when `release-label` is empty: `git-describe` (`git describe --tags --always --dirty`, e.g. `v0.1.1-2-g321798b`), `git-tag` (the exact tag on the commit), `package-json` (the `version` field), or `input` (only `release-label`). If the source yields nothing, the short commit SHA is used and a warning is logged. | | `package-json-path` | No | `package.json` | Read only when `release-label-from` is `package-json`. | | `target-id` | No | *(empty)* | Deprecated. A target created in Viewport. Runs are not attributed to a release. Cannot be combined with `product-id` or `environment`. | | `exploration-url` | No | *the target's URL* | Override the URL to explore. Only with `target-id` - an environment owns its URL. | | `url` | No | - | Deprecated alias for `exploration-url`. | | `run-exploration` | No | `true` | Start an exploration. | | `wait-for-deployment` | No | `false` | Wait until the environment serves the pushed commit before starting. Your app must return its deployed commit in a response header. | | `wait-for-deployment-timeout-seconds` | No | `300` | How long to wait before failing the step. | | `wait-for-deployment-interval-seconds` | No | `10` | Delay between checks. | | `wait-commit-header` | No | `x-commit-sha` | Response header carrying the deployed commit (full or 7-character SHA). | | `wait-commit-path` | No | `/` | Path checked on each poll, e.g. `/api/health`. | | `api-url` | No | `https://platform.duku.ai/graphql` | Platform API endpoint. | | `auth-url` | No | *derived from api-url* | Authentication server URL. | | `github-installation-id` | No | - | Duku AI GitHub App installation ID. Normally auto discovered. | | `repository` | No | - | Repository in `owner/repo` format. Set this together with `pr-number` to attach PR metadata and post the sticky PR comment on non `pull_request` triggers. | | `pr-number` | No | - | Pull request number. Set this together with `repository` to attach PR metadata and post the sticky PR comment on non `pull_request` triggers. | | `github-token` | No | *(empty)* | On `pull_request`, posts the status comment (needs `pull-requests: write`). On `push`, links the pull requests the pushed commits came from to the release that shipped (needs `pull-requests: read`). Optional - without it those steps are skipped. Unused on `schedule` and `workflow_dispatch`. | ### PR metadata on non `pull_request` triggers Set `repository` and `pr-number` together when you run on `push`, `workflow_dispatch`, or `repository_dispatch` and still want the action to attach PR metadata and post the sticky PR comment. This is useful when the PR or URL is only known later in the pipeline. When you omit these inputs, behavior on a native `pull_request` event is unchanged. ### `environment` outputs | Name | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `target-id` | The build the run was attributed to. | | `release-id` | The release the build was recorded as. Empty when using `target-id`. | | `run-id` | ID of the exploration. Empty when `run-exploration` is `false`. | | `run-status` | `triggered` (running asynchronously - see Viewport for the final status), or `skipped` when `run-exploration` is `false`. | | `comment-id` | ID of the sticky PR comment. Set on a native `pull_request` event, or on other triggers when `repository`, `pr-number`, and a `github-token` are present. | ### Release names With `product-id`, each commit is recorded as one release. By default its name comes from `git describe`, so check out the repository with tags first: ```yaml - uses: actions/checkout@v4 with: fetch-depth: 0 ``` Pass `release-label` to use your own name, for example a version your build step outputs. If a commit already has a release under a different name, the existing name is kept and the step logs a warning - rename the release in Viewport instead. ### Secrets and variables to configure | Name | Kind | Used by | Description | | --------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------ | | `PLATFORM_API_KEY` | secret | both | Platform API key from Viewport - **Settings → API Keys**. | | `PLATFORM_PRODUCT_ID` | variable | both | Duku product ID from Viewport - **Products**. | | `DUKU_STAGING_TARGET_ID` | variable | environment | Only needed with the deprecated `target-id` input. | | `VERCEL_AUTOMATION_BYPASS_SECRET` | secret | preview | Optional bypass secret for Vercel Deployment Protection on protected previews. | ### Versioning and pinning Each action is versioned independently with an `/v` tag: ```yaml # Pin to a specific release. Recommended for reproducibility. - uses: duku-ai/actions/preview@preview/v0.5.0 - uses: duku-ai/actions/environment@environment/v0.5.0 ``` Both actions release together at the same version from 0.5.0. Both actions are currently pre release in `0.x`, so pin to a specific immutable tag. A floating major tag, such as `preview/v1`, becomes available once an action ships its first stable `v1.0.0` release. The `preview` action's explorations get a GitHub check run on the pull request - see GitHub check runs. The action itself exits as soon as the exploration starts, so its exit code does not reflect the result. ### Read next * Quickstart: preview action * Quickstart: environment action * Troubleshooting