You can connect a GitHub repository to an App Platform app and deploy the branch you choose with one click. This guide covers connecting public and private repositories, deploying, reading the build log, and how to get deploy-on-push today through your CI.
In your app's GitHub tab, enter the repository URL and branch, add an access token if the repository is private, and click Connect Repository. Then click Deploy Now whenever you want to ship. Pushing to GitHub does not start a deploy by itself at the moment. For deploy-on-push, add a deploy-token step to GitHub Actions, GitLab CI or Bitbucket Pipelines, using the examples in the Deploy Tokens tab.
The GitHub tab marks "Auto-deploy on push" as unavailable. Pushing a commit does nothing on its own. After you push, click Deploy Now, or let your CI deploy with a token (section 4).
1. Before you start
- An App Platform app, created from Services › App Platform.
- A repository whose root holds your app:
package.jsonfor a Node.js app, or aDockerfilefor Python, PHP and anything else. Only Node.js is detected automatically. See the App Platform overview. - For a private repository: a GitHub personal access token with
reposcope.
2. Connect your repository
- Open your appand go to Access › GitHub.
- Enter the repository URLin full, for example
https://github.com/username/repo. - Choose the branchto deploy, usually
main. The name must match exactly:mainandmasterare different branches. - Add an access token for a private repository.Leave the field blank for a public one.
- Click Connect Repository.
The access token is stored encrypted and never shown back to you. To replace it, enter a new one and click Save Changes; leave the field blank to keep the saved token. Remove saved token deletes it, after which deploys from a private repository fail. Disconnecting the repository also removes the token.
3. Deploy with Deploy Now
Click Deploy Now in the GitHub tab. We pull the branch you chose, install dependencies, build the app, run a health check and switch traffic to the new version with no downtime.
The build output streams into the page while it runs. If the live stream can't connect, the deploy still carries on; check the Deploys tab for the result. If a build fails, the version that was already running keeps running.
4. Deploy on every push, using your CI
This is the way to get deploy-on-push today. It works from GitHub, GitLab or Bitbucket.
- Create a tokenin the app's Access › Deploy Tokens tab. Copy it straight away; it is shown only once.
- Store it as a secretin your repository settings, under the secret name the tab's example uses. Never paste the token into a file in the repository.
- Pick your CI providerunder "From your CI, on every push" and copy the ready-made job for GitHub Actions, GitLab CI or Bitbucket Pipelines.
- Commit the job fileand push. Each push to your main branch then packages your code and uploads it with the token.
Copy the job from the tab rather than from another guide: it already contains your app's deploy address. The details are in Deploying with a deploy token.
5. Watch a deploy
- Go to Deploy › Deploys.
- Open the most recent deployment and show its build log.
If a deployment shows "Not started: platform busy", the platform was building other apps and nothing was built. Deploy again in a few minutes.
6. Disconnect a repository
Click Disconnect in the GitHub tab and confirm. Your app keeps running exactly as it is, and you can reconnect at any time.
7. If connecting or deploying fails
| Problem | What to check |
|---|---|
| Connection won't save | The URL is the full https://github.com/user/repo form, and the branch name matches exactly |
| Private repository fails to clone | The token has repo scope, hasn't expired, and belongs to an account that can read the repository |
| Pushed, but nothing deployed | Expected: push doesn't deploy by itself. Click Deploy Now, or set up the CI job |
| Build fails | Read the build log in the Deploys tab; see Troubleshooting the App Platform |
If it still won't connect, open a ticket with your app name and repository URL. Never send us your access token.
Does pushing to GitHub deploy my App Platform app automatically?
Not at the moment. Automatic deploy on push is unavailable. Click Deploy Now in the GitHub tab after you push, or add a deploy-token job to your CI so each push uploads and deploys your code.
Can I deploy from a private GitHub repository?
Yes. Add a GitHub personal access token with repo scope when you connect the repository. It is stored encrypted, never shown back to you, and removed when you disconnect.
Can I deploy from GitLab or Bitbucket?
Yes, with a deploy token. The Deploy Tokens tab has ready-made jobs for GitHub Actions, GitLab CI and Bitbucket Pipelines.
What happens to my running app if a build fails?
Nothing. The version that was already running keeps serving until a new build passes its health check.
Does disconnecting GitHub stop my app?
No. Your app keeps running as it is. Only the link to the repository and the saved access token are removed.
Ready to connect your code? Open your App Platform apps, see App Platform plans, or ask us in a support ticket.
GitHub deploys and deploy tokens are included in every App Platform plan.
See App Platform plans