Docs
Sign in
On this page

GitHub App

Install the StitchDB GitHub App: every pull request gets a preview branch with its migrations applied, a check and a comment with the branch URL.

The StitchDB GitHub App connects a repository to a project. Every pull request gets its own preview branch, with the migrations from the pull request applied. You don't need a workflow file or a token in the repository.

#What happens

  • Pull request opened, or new commits pushed: StitchDB creates the branch for the pull request's git branch, or reuses it. It applies stitchdb/migrations/*.sql from the latest commit in version order, skipping files that are already applied. A StitchDB preview check shows the result, and one comment shows the branch's API URL, project ref and dashboard link. That same comment is updated on every push.
  • A migration fails: the check fails with the Postgres error, and the comment says which file failed.
  • Pull request merged or closed: the branch is deleted. It is kept if another open pull request uses the same git branch.
  • Push to the production branch (optional): new migrations are applied to the project itself, with a StitchDB production check on the commit.

#Set up

  1. Open the project and go to Integrations › GitHub, then click Install the GitHub App.
  2. On GitHub, choose your account or organization and the repositories the app may read. GitHub then asks you to authorize the app, which lets StitchDB check that the installation is yours.
  3. Back in the dashboard, click Link a repository. Choose the repository, the production branch, and the folder that holds migrations/ (stitchdb unless you changed it with stitchdb init).

#Options

  • Masked production data: branches start with a copy of production in which personal data is replaced. See Preview branches. This needs a plan that includes branch data.
  • Apply on push: pushes to the production branch apply new migrations to this project. Leave it off if you deploy with stitchdb db push or the GitHub Actions workflow. Use only one of these, so that migrations aren't pushed twice.

Branches count against your plan's branch limit. If the limit is reached, the check fails with the reason and no branch is created.

#API

Terminal
# Status, installations and recent runs
curl https://stitchdb.com/platform/v1/projects/$REF/integrations/github -H "Authorization: Bearer $STITCHDB_TOKEN"

# Link a repository (the installation must already be set up from the dashboard)
curl -X PUT https://stitchdb.com/platform/v1/projects/$REF/integrations/github \
  -H "Authorization: Bearer $STITCHDB_TOKEN" -H "content-type: application/json" \
  -d '{"installation_id": 12345678, "repo_id": 87654321, "production_branch": "main", "dir": "stitchdb"}'

To stop, uninstall the app on GitHub, or remove the repository from the installation. Either one unlinks the project. Existing branches stay until you delete them.

Was this helpful?