GitHub App

The VibeView GitHub App builds your app in the VibeView cloud whenever you push to GitHub, and makes a signed production build when you push a version tag. There is no workflow file to write and no API token to store. Each build shows up as a check on the commit. A pull request also gets one comment that lists its builds, with a link to run each one on a cloud device.

Pushes and pull requests make simulator builds for iOS and Apple TV and emulator builds for Android and Android TV: an unsigned preview build profile when the project has one, else development (see Choose a build profile). Version tags make production builds, ready to download or submit (see Version tags). The builds are the same ones vibeview build --cloud makes (see Cloud builds), so your repository needs a vibeview.json with a build block for each platform it builds.

If you’d rather run builds from your own CI, see Cloud builds in CI.

Install the App

You need the Admin role in VibeView. On GitHub, you need to be an owner of the organization (or the owner of the personal account) you install the App on.

1. Go to Settings > Integrations and find the GitHub App card.
2. Click Install on GitHub.
3. On GitHub, pick the account or organization and the repositories VibeView may read, then confirm.
4. GitHub sends you back to VibeView, and the account and its repositories appear on the card.

If you’re a member of a GitHub organization but not one of its owners, GitHub asks an owner to approve the install, and VibeView shows “Waiting for an owner of the GitHub organization to approve.” Only an owner can link the installation to VibeView, so the simplest path is for an owner of the GitHub organization who is also an Admin in your VibeView organization to install it from VibeView.

If you install the App on GitHub instead (from GitHub Marketplace or the App’s page), GitHub sends you to VibeView afterwards. Sign in, click Link to VibeView, and confirm on GitHub: VibeView checks that you own the GitHub account it’s installed on, then links it like an install started here. You need the Admin role. If you created your VibeView account on the way and didn’t see that page, open the App’s settings on GitHub (your account or organization settings > GitHub Apps > VibeView > Configure) and click Save: GitHub sends you back to Link to VibeView.

A GitHub installation can be linked to one VibeView organization only.

To add or remove repositories later, change the App’s repository access on GitHub (your account or organization settings > GitHub Apps > VibeView > Configure). The card follows.

Unlink (Admins) stops all builds from that GitHub account and forgets its repositories’ settings. The App stays installed on GitHub until you uninstall it there.

Configure a repository

Developers and Admins configure repositories. Viewers see the settings but can’t change them.

On the card, click Configure next to a repository:

• Build this repository: builds are off until you turn this on. You can also switch it from the Builds column.
• Branches: pushes to these branches build. By default this is the repository’s default branch. Patterns work too, for example release/*.
• Pull requests: build pull requests opened from a branch of this repository (on by default).
• Build profile: the vibeview.json profile that pushes and pull requests build. Leave it empty for automatic. See Choose a build profile.
• Version tags: make a build when you push a new tag that matches Tag pattern (off by default; the pattern is v* unless you change it). Tag profile picks the profile tags build; empty means production, a signed build.
• Projects: one row per build. Each row has the folder that holds the vibeview.json (leave it empty for the repository root), the platform, and the VibeView app the build goes to. Only apps of that platform are listed.
• Detect from vibeview.json reads the vibeview.json files on the default branch and fills in the projects for you. If a file’s app id matches one of your apps, it picks that app.
• Only build changed projects shows up when the projects live in more than one folder. See Monorepos.

Choose a build profile

Each platform’s build block in vibeview.json can hold several build profiles. The repository’s settings pick which one each trigger builds:

Pushes and pull requests never make signed builds. If Build profile names a profile that is a signed production build, that project’s check fails and says so. A profile the project’s vibeview.json doesn’t have fails its check too, and the check says what to add. On automatic, a project whose only preview is signed and that has no development profile fails its check the same way.

Builds start on behalf of the person who last saved the repository’s settings, and are billed to your organization like any other build. If that person leaves the organization or loses the Developer or Admin role, the repository’s checks say so, and the builds don’t start until a Developer or Admin saves the settings again.

What builds

• Pushes to a branch in Branches. Deleting a branch builds nothing.
• Pull requests opened, reopened or updated with new commits, when Pull requests is on. Draft pull requests build too.
• Pull requests from forks never build. VibeView ignores them completely. Nothing from a fork is downloaded or stored.
• Version tags that match Tag pattern, when Version tags is on: a build of every project with the Tag profile (a signed production build unless you pick another profile). Only a newly pushed tag builds. Moving or deleting a tag builds nothing.

Skip a build

Put [skip ci], [ci skip] or [vibeview skip] in the commit message. For a pull request, the message of its newest commit counts. VibeView doesn’t build it, and the check says “Skipped by commit message”.

Monorepos

With projects in more than one folder and Only build changed projects on, a push or pull request builds only the projects whose folder it changed. The other projects get a neutral check, “No changes in this project”. A change to the root vibeview.json, or to a file outside every project folder, builds all of them. If GitHub can’t list the changed files (a very large change, for example), every project builds.

Version tags

With Version tags on, pushing a new tag that matches the pattern (for example git tag v1.4.0 && git push origin v1.4.0) builds each project’s Tag profile. Left empty, that is the production profile from the project’s vibeview.json (see App signing): the build is signed with the app’s signing credential and lands on the Builds page, labelled with the tag, ready to download or submit.

To make an unsigned build from tags instead, set Tag profile to another profile, for example preview. That build needs no signing and runs on a cloud device like a pull request’s build.

• A project’s vibeview.json needs the tag profile for each platform. Without it, that project’s check fails and says what to add.
• A signed build needs signing set up for the app first. Without a valid signing credential, VibeView starts nothing and the check says Signing isn’t set up, with a link to the Signing tab. Upload or fix the credential, then use Re-run all checks on the tag’s commit.
• A tag’s checks are named after its profile, for example VibeView: iOS, production (VibeView: <folder> (<platform>, production) in a monorepo), so they never get mixed up with a branch build of the same commit. Branch and pull request checks keep their plain names whatever profile they build.
• [skip ci] and the other skip keywords don’t apply to tags: pushing a release tag is the request. Only build changed projects doesn’t either, so every project builds.
• A tag’s build counts like any other cloud build.
• To send each tag’s production build to its store when it succeeds, add "autoSubmit": true to the platform’s submit settings in vibeview.json (for example "submit": { "groups": ["Internal"], "autoSubmit": true } under platforms.ios). The build goes to TestFlight or Google Play with those settings, as vibeview build --cloud --production --auto-submit sends it; a tag has no notes, so use internal TestFlight groups. Without the store’s key, VibeView doesn’t start the build and the check says why. See Submit automatically after a build.

Checks, the pull request comment and Re-run

Every project and platform gets its own check on the commit, named VibeView: <folder> (<platform>) (or VibeView: <platform> for the repository root). The check moves from queued to in progress to its result, and Details opens the build in VibeView. When a build for simulators or emulators succeeds (any profile but a signed one), the check links Run on a simulator (or Run on an emulator), which opens the Devices page with that build picked: choose a device and the build starts on it.

A pull request gets one VibeView comment. It’s a short table for the pull request’s newest commit: each project and platform with its status, a link to the build and, once it succeeds, the same Run link as the check. VibeView edits the same comment as builds progress and as you push more commits, so it never piles up comments. If you delete the comment, the next update posts a new one.

The build links open only for people signed in to your VibeView organization, even when the repository is public.

Re-run on a VibeView check starts that one project’s build again, on the same commit. Re-run all checks does the same for every VibeView check on the commit.

When you push a new commit to a pull request, VibeView cancels the pull request’s earlier builds that are still queued or running, and their checks say “Superseded by” the new commit. Pushes to a branch aren’t cancelled this way.

On the Builds page and the build’s own page, each build is labelled with its commit and branch and links to the pull request (or the commit). The build’s page says “Started by GitHub ()”, naming the GitHub user who pushed.

Run pull request builds on a device

A React Native or Expo development build loads its JavaScript from a Metro dev server on your computer, so on a cloud device it only shows an error screen. For such a build the check and the comment say Debug build instead of offering Run.

To open a pull request’s build on a device, add a preview profile to the project’s vibeview.json: the same build in Release, with the JavaScript inside the app (see Build profiles). With Build profile left on automatic, pushes and pull requests then build preview, and the check and comment offer Run. vibeview build and vibeview dev write a preview profile for you when they set up a React Native or Expo project and you accept the suggested build command (on Android, only while the release build is still signed with the debug key: see Bare React Native projects); for a project set up earlier, run vibeview build --cloud --profile preview once on your machine: it suggests the Release build (on Android signed with your own keystore it suggests nothing, and you enter the command yourself), saves it to vibeview.json and builds it. Then commit the updated file.

If the project’s preview is a signed build (Expo projects often sign theirs for testers), automatic skips it and builds development, because pushes and pull requests never sign. Add an unsigned profile of your own (the same Release build with "distribution": "simulator") and pick it in Build profile.

Native, Flutter, Capacitor and Kotlin Multiplatform development builds don’t need Metro, so they run as they are.

If you need a VibeView check to pass before merging, add it as a required status check in your branch protection rules on GitHub.

What it costs

A build from the GitHub App is billed exactly like any other cloud build: its builder time counts toward your plan’s included build minutes for the month, and beyond them it is billed by the minute to usage credit (see Cloud builds and Pricing). Only the branches and pull requests you turn on build, so choose Branches with care: building every push adds up quickly.

When a build can’t start, its check says why, with Action required and a link to the page that fixes it. For example, when you’re out of included build minutes and usage credit, or at your storage limit, the check shows the same message the dashboard would and links to Plan and usage. VibeView never skips a build silently.

Limits

• What gets built: VibeView downloads the commit it builds from GitHub. The source is the commit’s files minus the paths the CLI always leaves out (node_modules/, ios/Pods/, .git/) and the paths in your .vvignore. A commit’s source archive may not exceed 2 GB.
• Git LFS and submodules aren’t supported. GitHub’s source archive has no submodules, and LFS files may arrive as small pointer files instead of their contents. When the repository has a .gitmodules file, the check notes that submodules weren’t included.
• Files marked export-ignore in .gitattributes aren’t in GitHub’s source archive, so they aren’t in the build either.
• Rate limits: at most 30 builds requested an hour for each repository, and at most 5 waiting to start for each VibeView organization. Beyond that, the check says so and asks you to push again later.
• GitHub.com only. Self-hosted GitHub servers aren’t supported.

Related

• Cloud builds: vibeview.json, build profiles and the Builds page
• Cloud builds in CI: build from GitHub Actions or another CI with the CLI
• GitHub checks: post test results as commit statuses