Merge to main, ship: environments that follow a branch

Until now, shipping an app meant running ib-apps deploy or pressing Deploy in the dashboard. Once a team works from pull requests, that's the step everyone forgets. Now an environment can follow a branch on GitHub. A push to the branch updates the environment, and a merge to main deploys production.

Connecting a repository

Open Settings → Git on the app. The repositories listed are the ones your team's Inference Bureau GitHub App can read. It's the same App Auditor uses, so a repository Auditor already reviews is ready to pick. Install on GitHub adds the App, or a repository to it, and GitHub sends you back.

For each environment, choose Follow a branch and pick:

• Repository: one the App can read.
• Branch: such as main or staging. An environment follows at most one branch, but several environments can follow the same one.
• Folder: optional. For a monorepo, the folder holding the app's package.json and settings.ib.ts, such as apps/portal.
• Through: production only, explained below.

The first sync, of the branch as it is now, runs within a minute. Owners and admins set this up, since they're the ones who can deploy.

Mapping branches to environments

Production never takes files straight from GitHub. It follows a branch through a development environment that follows the same branch. The push lands in that environment, and production then deploys from it like any other deploy. The deploy plan, the build, the Shopify release and rollback work as usual.

A common setup has three environments:

• development follows your working branch
• staging follows main
• production follows main through staging

A merge to main then updates staging and ships production. Settings → Deploys shows which commit production runs.

What happens on a push

The commit's files are read, hashed and compared with the environment's, as ib-apps push does with a folder:

• Files that differ are pushed, and files the commit no longer has are deleted.
• .ibignore applies, and .git, node_modules, .next and the other never-synced folders stay out.
• The dev server picks up the change and reloads, and a Shopify app's extensions release.
• If production follows the branch, it deploys from the development environment once the files are in.

Each sync is a GitHub Deployment on the commit, named after the app and environment, such as portal (production). It succeeds with the environment's address, or fails with a link to its Logs.

A followed environment changes only through its branch. The file editor shows it read-only. The assistant, ib-apps push and production's Deploy button are refused, with the branch named. Roll back still works. If the branch is deleted or the repository is removed from the App, the following stops and the files stay as they are.

A deploy-plan check on every pull request

A merge is the wrong time to learn that a deploy will break production's data. So a pull request into a followed branch gets a check on its head commit, Deploy plan · <app>. It says what deploying that commit would do to production as production runs now:

• the files it adds, changes and removes
• each model change
• how many of production's records each change reaches

The check fails when a change would reach records production already holds. That means a removed field or model that still holds values, a new type that some stored values can't take, or a new required or unique rule that existing records already break. It also fails on a schema that can't be read. Under Pull requests on Settings → Git you can make it warn instead of fail, or turn it off. It doesn't include type errors: the production build type-checks pages.

Web apps can also turn on preview environments. Each pull request then gets pr-<number>, which follows the pull request's branch and is deleted at merge or close. Shopify apps don't get previews yet, because each one would need its own store install.

If you keep your own CI

If you'd rather deploy from your own workflow, create a deploy token under Settings → Git. It reaches one development environment. Push lets it change that environment's files, and Push and deploy also lets it deploy production from there. It never reaches records, settings or other environments. With @inferencebureau/apps 0.10.0 or later, the token goes in a GitHub Actions secret:

npx -y @inferencebureau/apps@latest push --app portal --env staging
npx -y @inferencebureau/apps@latest deploy --app portal --env staging

Run both steps with IB_API_KEY set to the token. In a fresh checkout, push --app --env sends what the folder has and deletes what's only on the server, as a sync from GitHub does. Settings → Git shows the full workflow file when you create a token.