GitHub integration

Connect a GitHub repository to an app and every push becomes a deployment. You install the Unkey GitHub App once, connect a repository, and push.

​

Install the GitHub App

You install the Unkey GitHub App once per workspace, on a GitHub organization or personal account, and choose which repositories it can see.

1. Start from any of these places in the dashboard: Connect GitHub when you create an app, the Repository row on an app’s App settings > Build page, or workspace settings.
2. Approve the installation on GitHub. GitHub sends you back to Unkey.

To do it with the API, call github.installApp with a root key that has workspace.*.install_github, and open the URL it returns. An installation belongs to one workspace only, so a second workspace can’t use it.

​

Add another GitHub account or organization

You can install the app on more than one GitHub account. For example, install it on your personal account and on your company’s organization.

1. In the new-app flow, open the account menu above the repository list.
2. Choose Add GitHub account at the bottom of the menu.
3. On GitHub, pick the account or organization, choose its repositories, and approve. GitHub sends you back to Unkey.

The new account now shows in the account menu. To install the app on an organization, you must be an owner of it on GitHub. Otherwise, GitHub sends the request to an owner to approve.

​

Connect a repository to an app

Pick the repository when you create the app, or later under App settings > Build. From the CLI, pass --git to create-app or update-app. You connect a repository per app, not per project. In a monorepo, two apps can connect to the same repository and use different build settings. The app’s default branch deploys to production. It starts as the repository’s default branch on GitHub, and you can change it with apps.updateApp. To stop deploying from pushes, click Disconnect repository in the danger zone of the app’s App settings > General page. The dashboard warns that “Unkey will stop building pushes to this repository. Running deployments stay live.”

​

What deploys when you push

Two things on GitHub create a deployment:

• A push to a branch. The first push of a new branch counts, which is how a branch gets its first preview. Pushing a tag or deleting a branch doesn’t deploy.
• A pull request from a fork, when it’s opened or gets new commits. Pull requests from branches in your own repository don’t deploy again, because the push already did.

The branch picks the environment. The app’s default branch (or main if none is set) deploys to production. Every other branch, and every fork pull request, deploys to preview. If several apps are connected to the repository, one push creates one deployment per app.

​

Skip deploys with auto deploy and watch paths

Two build settings can stop a push from deploying. We check them in this order:

1. Auto deploy off. The push is recorded as skipped with “Auto deploy is disabled for this environment.” Watch paths aren’t checked.
2. Watch paths set, and no changed file matches. The push is skipped with “Watch paths did not match any changed files.” If a pattern isn’t a valid glob, it’s skipped with a message naming the pattern.

Otherwise, we create a deployment. Watch paths also apply to fork pull requests. Patterns use ** globbing. src/** matches everything under src, **/*.go matches every Go file, and a pattern with no wildcard matches only that exact path.

​

Approve pull requests from forks

A fork pull request runs code from someone without write access to your repository, with your environment variables. So we never build it automatically.

1. The deployment waits in awaiting_approval. On the pull request, a failing check named Unkey Deploy Authorization says “Awaiting authorization from a project member” and links to the deployment.
2. A project member approves it in the dashboard. The build starts.

Pushes from people with write access to the repository don’t need approval. Fork previews get their own hostname prefix, <project>[-<app>]-fork-<fork owner>-..., so you can’t confuse them with your own branches. You can also deploy a fork yourself from the Create Deployment dialog, or with deployments.createDeployment by passing git.repository as owner/repo and a commitSha.

​

Use Git submodules

We clone your repository’s submodules with it, at the commits your repository pins. Public submodules always clone. A private submodule clones when all of these are true:

• Its url in .gitmodules is an HTTPS GitHub URL, such as https://github.com/acme/shared.git, or a relative URL, such as ../shared.git.
• The same GitHub account owns the submodule and the repository you deploy.
• The Unkey GitHub App has access to the submodule’s repository. To add it, change the app’s repository access in your GitHub account or organization settings.

These private submodules don’t clone:

• Submodules with SSH URLs, such as git@github.com:acme/shared.git
• Submodules nested inside another submodule
• Any private submodule in a build of a fork pull request

If a submodule can’t be cloned, the build fails with “A Git submodule could not be cloned.”

​

What you’ll see on GitHub

Each deployment of a connected app reports back to GitHub:

• A GitHub Deployment on the commit, labeled project - env (or project/app - env when the app isn’t default), linking to the environment’s unkey.app domain. Its status goes from “Deployment queued” to “Deploying to regions…”, “Configuring routing…”, and “Deployment is live”, or to a failure that names the step that failed.
• A pull request comment, when the branch has an open pull request or the deployment came from a fork. We keep one comment per pull request up to date, with a row per app and environment: status, a Visit Preview link, an Inspect link to the dashboard, and when it last changed.
• A commit status, only for fork deployments waiting for approval.

​

Troubleshooting: a push didn’t deploy

Check these in order:

1. The Unkey GitHub App is installed on the account that owns the repository, and has access to it.
2. The repository is connected to the app under App settings > Build.
3. Auto deploy is on for the environment the branch maps to (the Auto-deploy switch on the environment’s page under App settings > Environments).
4. The push changed a file that matches the watch paths, if any are set.
5. The app’s deployments list shows a skipped or failed row with the reason.

​

Next steps