GitHub Status Checks

Post test results as commit statuses on GitHub. See pass/fail directly in pull requests.

Quick Start

1. Go to Settings > Integrations.
2. Add a GitHub Personal Access Token with the repo:status scope.
3. Provide the repository owner and name.
4. Run a test suite with --commit-sha — the status appears on the commit in GitHub.

GitHub Workflow Template

Use the VibeView workflow template to automate testing in any GitHub repository. The workflow handles app upload, test creation, execution, and PR reporting in a single job.

Minimal Setup

Create .vibeview/test-spec.json in your repo:

{
  "version": 1,
  "steps": [
    "Launch the app",
    "Verify the home screen loads"
  ]
}

The app build path comes from the workflow’s APP_PATH env var, not the spec file. Platform is auto-detected from the binary at upload time. See CI Testing for the full schema.

Add the VibeView workflow template to your repository: copy templates/vibeview-test.yml (provided by VibeView) to .github/workflows/vibeview-test.yml, set the APP_PATH env var to your build output, and add the VIBEVIEW_API_TOKEN and VIBEVIEW_NPM_TOKEN secrets. See CI Testing — Workflow Template for full setup.

The workflow:

1. Reads .vibeview/test-spec.json for test configuration.
2. Uploads the app build to VibeView.
3. Creates and runs an AI test with the specified steps.
4. Posts a PR comment with pass/fail results and a link to the run detail page.
5. Sets the commit status check (vibeview/tests) via --commit-sha.

When a run passes but carries visual regressions, the PR comment shows a yellow ⚠️ warning (header, suite rows, and individual case rows) instead of a plain green ✅ — matching the dashboard. This is informational and non-blocking: the commit status stays success so the PR remains mergeable. The warning is driven by the visual_regression_status field (ok / warn / fail) returned per case, per suite, and at the aggregate level by the /api/v1/ci/multi-suite-runs/:id endpoint.

For workflow-template setup, see CI Testing.

Connecting GitHub

Navigate to Settings > Integrations in the VibeView dashboard, or connect via the API:

curl -X POST https://vibeview.io/api/v1/integrations/github \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pat": "ghp_your_personal_access_token",
    "default_owner": "your-org",
    "default_repo": "your-repo"
  }'

Token requirements: Your GitHub PAT needs the repo:status scope to post commit statuses.

VibeView encrypts the PAT at rest. Only one GitHub integration exists per organization — connecting again updates the existing configuration.

Testing the connection:

curl -X POST https://vibeview.io/api/v1/integrations/github/test \
  -H "Authorization: Bearer YOUR_TOKEN"

This verifies the PAT can access the configured repository and returns {"success": true} or an error message.

How It Works

When a suite run includes a commit_sha, VibeView automatically posts a commit status to GitHub:

1. Run starts — a pending status is posted: “VibeView: Running ‘Suite Name’…”
2. Run completes — the status updates to one of:
   • success — “VibeView: ‘Suite Name’ passed”
   • failure — “VibeView: ‘Suite Name’ failed”
   • error — “VibeView: ‘Suite Name’ errored”

The status context is vibeview/tests — this is the label that appears in the pull request checks list.

Each status includes a target URL linking back to the suite run in VibeView (https://vibeview.io/tests/<suite-id>), so reviewers can click through to see full results.

CI/CD Integration

CLI with Commit SHA

Pass --commit-sha to the CLI to associate a run with a commit:

vibeview run-suite <suite-id> --commit-sha $(git rev-parse HEAD)

CI API Endpoints

VibeView provides dedicated CI endpoints at /api/v1/ci/ for headless test execution:

Start a suite run:

curl -X POST https://vibeview.io/api/v1/ci/run-suite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "suite_id": "abc123",
    "commit_sha": "a1b2c3d4e5f6",
    "mode": "hybrid"
  }'

Returns {"run_id": "...", "status": "pending"}.

Poll for results:

curl https://vibeview.io/api/v1/ci/runs/<run_id> \
  -H "Authorization: Bearer YOUR_TOKEN"

The response includes status (pending, running, passed, failed, error), per-case results, duration, and timestamps.

GitHub Actions Example

Option 1: VibeView workflow template (recommended for AI-powered test-spec workflows)

Use the VibeView workflow template for a copy-paste setup with automatic PR comments. See CI Testing — Workflow Template for full details.

Option 2: Direct CLI (for existing suite runs)

name: VibeView Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          registry-url: https://npm.pkg.github.com
          scope: '@scriptx-com'

      - name: Install VibeView CLI
        run: npm install -g @scriptx-com/vibeview-cli
        env:
          NODE_AUTH_TOKEN: ${{ secrets.VIBEVIEW_NPM_TOKEN }}

      - name: Run test suite
        env:
          VIBEVIEW_API_TOKEN: ${{ secrets.VIBEVIEW_API_TOKEN }}
          VIBEVIEW_BASE_URL: ${{ secrets.VIBEVIEW_BASE_URL }}
        run: |
          vibeview run-suite ${{ secrets.SUITE_ID }} \
            --commit-sha ${{ github.sha }} \
            --output junit > results.xml

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: vibeview-results
          path: results.xml

This workflow:

1. Installs the CLI.
2. Runs the suite with the current commit SHA (triggers GitHub status posting).
3. Outputs JUnit XML for artifact upload.

The vibeview/tests check appears in the pull request automatically.

Managing the Integration

Check connection status:

GET /api/v1/integrations/github

Returns the configured owner, repo, and a masked token prefix for verification.

Disconnect GitHub:

DELETE /api/v1/integrations/github

Removes the PAT and disables commit status posting.

Troubleshooting

• Status not appearing: Verify the PAT has repo:status scope. Run the test endpoint to confirm access.
• Wrong repository: The owner and repo must exactly match the GitHub repository where you want statuses posted.
• Delayed status: Statuses are posted after the suite run completes. If the run takes several minutes, the status appears when it finishes.
• “vibeview/tests” not in PR checks: The commit SHA must match a commit on the pull request branch. Use ${{ github.sha }} in GitHub Actions or $(git rev-parse HEAD) in other CI systems.