GitHub Status Checks

Post VibeView test results as commit statuses on GitHub, so each group’s pass or fail shows up in the pull request’s checks.

Quick Start

1. Create a GitHub token that can write commit statuses on your repository (see Token requirements).
2. In VibeView, go to Settings > Integrations and click Connect GitHub (this needs the Admin role). Enter the token, the repository owner and the repository name.
3. Run groups with --commit-sha set to the commit you tested. The workflow template does this for you, with the pull request’s head commit.

Status names

Every group run posts its own status, named after the group and its platform:

vibeview/<suite name> (<platform>)

For example vibeview/Checkout (ios) and vibeview/Checkout (android). The platform is ios, android, tvos (Apple TV), androidtv (Android TV) or roku: the group’s own platform, or else its app’s. A single test run (vibeview run-test --commit-sha) posts vibeview/<test name> (<platform>) the same way.

Because each group has its own status, a group that passes can’t hide an earlier group’s failure on the same commit, and the iOS and Android runs of one pull request don’t overwrite each other. Renaming a group changes its status name.

How It Works

When a run has a commit SHA and your organization has connected GitHub, VibeView posts:

1. When the run starts: a pending status: “VibeView: Running ‘Checkout’…”
2. When it ends: one of
   • success: “VibeView: ‘Checkout’ passed”
   • failure: “VibeView: ‘Checkout’ failed”
   • error: “VibeView: ‘Checkout’ errored” (also for a cancelled run, or one that stopped for a reason that isn’t your app)

A run in which no step was checked (Not checked) is neither a pass nor a failure. Commit statuses have no neutral state, so it posts success with “VibeView: ‘Checkout’ not checked (no step was checked)”: it doesn’t block a merge, and the wording says nothing was verified.

A quarantined test’s failure doesn’t turn a check red: a group run whose only failures are quarantined posts success, and a single run of a quarantined test that failed posts success with “VibeView: ‘Checkout’ failed (quarantined)”.

Each status links to that run’s results page in VibeView.

On a run’s page, the commit the run was started with links to that commit on GitHub.

Statuses go to the one repository configured on the integration, and a status appears on a pull request only when it is posted on a commit of that pull request. In GitHub Actions, use ${{ github.event.pull_request.head.sha || github.sha }}: on a pull_request event, github.sha is a merge commit GitHub creates for the run, which isn’t part of the pull request. In other CI systems, use the commit you checked out and built (git rev-parse HEAD on a branch build).

Requiring VibeView before merging

To block merging until the tests pass, add a branch protection rule (or a ruleset) for your main branch with Require status checks to pass, then choose which checks to require:

• Recommended: the workflow’s jobs, VibeView (iOS) and VibeView (Android) in the workflow template. A job fails when any tagged group of its platform fails or can’t run, it covers groups you tag later, and it doesn’t depend on group names.
• Specific groups, such as vibeview/Checkout (ios). GitHub offers a status for selection only after it has been posted recently. A required status that is never posted blocks the pull request, so this breaks when you rename the group or remove its tag.

Two GitHub behaviors to plan for:

• Skipped jobs count as passing. The template skips pull requests from forks and from Dependabot (they get no secrets), and GitHub treats a skipped required job as successful. Review those pull requests before merging.
• Filtered-out workflows never report. When the template’s paths-ignore filter skips a pull request (one that changes only Markdown or docs/), its required checks stay “Expected” and the pull request can’t merge. If you require the VibeView jobs, remove the paths-ignore filter.

Token requirements

Use a fine-grained personal access token limited to the one repository, with the repository permission Commit statuses: Read and write. A classic token with the repo:status scope also works, but it can write statuses on every repository its owner can access.

VibeView encrypts the token at rest. Only one GitHub integration exists per organization: connecting again replaces the token and the repository.

Connecting GitHub with the API

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

Testing the connection:

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

This checks that the token can read the configured repository, and returns {"success": true} or an error message.

CI/CD Integration

CLI with Commit SHA

Pass --commit-sha to any run command:

vibeview run-suites --tag smoke --platform ios --build "$BUILD_ID" --commit-sha "$(git rev-parse HEAD)"
vibeview run-suite <suite-id> --commit-sha "$(git rev-parse HEAD)"
vibeview run-test <test-id> --commit-sha "$(git rev-parse HEAD)"

For GitHub Actions, start from the workflow template: it builds your app, runs your tagged groups against that build with the pull request’s head commit, and comments the results on the pull request.

CI API Endpoints

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

Start a group 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 the run’s id, its session id, and a status of pending, or queued when it is waiting for a free device.

Poll for results:

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

The response includes the run’s status (queued, pending, running, passed, failed, error or cancelled; a run in which nothing was checked reads passed with not_checked: true), per-case results, duration and timestamps. See Reading run results.

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 token and stops status posting.

Troubleshooting

• No status appears: check that the token can write commit statuses on the repository (use Test connection, or the test endpoint above), and that the owner and repository name exactly match the repository the commit is in.
• The status is on the wrong commit, or missing from the pull request: the commit SHA must be a commit of the pull request. In GitHub Actions, pass github.event.pull_request.head.sha, not github.sha (see How It Works).
• A required check stays “Expected”: the status or job never ran for that pull request. See Requiring VibeView before merging.
• Statuses from another repository: statuses are posted only to the repository configured on the integration. A CI run in any other repository still runs, but posts no status there.