Preview Build

The preview build feature lets you kick off a GitHub Actions workflow directly from a PR comment. When the run finishes, the bot updates that comment with the outcome and links to any uploaded artifacts.

---

How it works

1. Comment on a PR with something like @vgvbot generate a build from this branch.
2. The bot posts an acknowledgement comment and dispatches the configured workflow on the PR’s head branch.
3. When the workflow run starts, the bot records it alongside the PR context.
4. When the run finishes, the bot updates the acknowledgement comment with the result.

---

Enabling it

1. Open the repository’s settings in the dashboard.
2. Go to the Features tab.
3. Set Preview Build to On.
4. Optionally enter a workflow filename — for example preview.yml. It must match the filename inside .github/workflows/. When set, the bot always dispatches that exact workflow. When left blank, the bot selects a workflow automatically — see Smart workflow selection below.
5. Optionally set a Timeout (minutes) override. Defaults to 30 minutes.
6. Save.

---

Smart workflow selection

Smart selection only runs when the Workflow file field in the dashboard is blank. If a filename is configured, that workflow is always dispatched — no LLM matching occurs.

When no workflow is pinned, the bot reads the user’s comment, fetches the repository’s active GitHub Actions workflows, and uses the LLM to pick the best match.

• A confident single match is dispatched immediately.
• If multiple workflows are equally plausible, the bot asks the user to clarify by naming one of the candidates.
• If nothing matches, or the request is too vague, the bot replies that no matching workflow was found.

# bot-hint: convention

Add a comment at the top of a workflow YAML file to guide the LLM:

# bot-hint: Builds the Android debug APK for QA testing.
name: Preview Build
on:
  workflow_dispatch:

The hint strengthens confidence in an existing match. It is not a selection override — the bot still reads the full YAML content, step names, and job definitions as the primary signal. A hint alone will not cause a poor match to be selected.

---

Workflow requirements

The workflow must be triggerable via workflow_dispatch. No special inputs or outputs are required.

name: Preview Build

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: ./scripts/build_preview.sh
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: preview-apk
          path: build/app.apk

The bot links to the run’s summary page (where GITHUB_STEP_SUMMARY content appears) and lists names of any uploaded artifacts with direct download links.

---

GitHub App permissions

The bot needs actions: write permission on the repository. Without it, the dispatch call fails and the bot posts an error comment.

The GitHub App must also subscribe to the Workflow run event. Without this, the bot dispatches the workflow but never receives the completion webhook and never posts the result.

---

Outcome comments

Condition	Comment
Success	Preview build complete! [View summary](…) plus artifact links if any were uploaded.
Failure	Preview build failed. [View run](…)
Timed out	Preview build timed out after N minutes. [View run](…)

---

Preview build not configured

If preview build isn’t set up for the repository and a user triggers the intent, the bot replies:

Preview build is not configured for this repository. Ask a repository admin to enable it in the dashboard.