Deploying from GitHub

Connect a GitHub repository to a PocketBase instance, a frontend or a backend, and every push to the branch you choose builds and deploys it. There is no workflow file to write and no token to store: the PocketBase Cloud GitHub App reads the pushed commit and hands it to the same build pipeline as an upload.

Connecting happens in the portal. Uploading a folder and deploying with pbc keep working alongside it.

Prerequisites

• A project in the portal (Creating a Project)
• A GitHub repository with your app’s source
• Backends need the Pro plan (Plans and Billing); PocketBase instances and frontends work on every plan

Step 1: Connect a repository

You can connect a resource that already exists, or create a new one straight from a repository.

Using the portal

For an existing resource:

1. Open the PocketBase instance, frontend or backend and go to Settings
2. In the Connect a repository card, click Connect a repository

For a new resource:

1. Open the project’s PocketBase, Frontends or Backends tab
2. Click Deploy from GitHub

Then, in both cases:

1. The first time, click Install GitHub App and choose which repositories PocketBase Cloud may read. You return to the portal when it is done
2. Pick the GitHub account and the Repository
3. Set the Branch to deploy from (defaults to main) and, for a monorepo, the Root directory of this app
4. Leave Deploy on every push on, or switch it off to deploy only by hand
5. Click Connect and Deploy

The first build starts straight away.

The CLI has no connect command — installing the GitHub App runs through GitHub in the browser. To deploy from a terminal or your own CI instead, use pbc deploy or GitHub Actions.

Step 2: Let the platform recognise the app

Before connecting, the portal reads the repository to work out what it builds — a PocketBase instance, a frontend or a backend, and for a backend the runtime. It looks at pbc.json first, then at files such as package.json.

• Detected — the portal shows the kind, the runtime and the directory it will build from. Carry on.
• AI-suggested — when nothing in the repository names the runtime, it may be suggested by a model and marked as such. Check it before deploying, and commit the pbc.json the portal offers so later deploys do not guess.
• Not detected — point the Root directory at the app, or commit the pbc.json the portal offers, then click Check Again.
• Looks like something else — if the repository is, say, a frontend and you are connecting a backend, the portal refuses and offers to deploy it as a new resource of the right kind instead.

Step 3: Push to deploy

With Deploy on every push on, push to the branch:

git push origin main

Each push starts a new deployment in the resource’s deployment history. The repository card on Settings shows the branch, the root directory and the last deployed commit, linked to GitHub.

Deploy a commit by hand

With auto-deploy off, or to redeploy the latest commit on the branch:

Using the portal

• On the resource’s Settings page, click Deploy Now, or
• On a PocketBase instance’s or frontend’s detail page, click Deploy from GitHub

Using the CLI

pbc deploy uploads your local directory rather than pulling from GitHub. Use it when you want to ship what is on your machine; use the portal to deploy the branch.

Change or disconnect the repository

Using the portal

On the resource’s Settings page:

• Click Edit on the repository card to open Repository settings and change the Branch, the Root directory or Deploy on every push. A new branch must already exist on GitHub
• Click Disconnect to stop deploying from GitHub. The resource keeps running on its last deploy, and you can reconnect later

The connection is managed in the portal only.

When a push does not deploy

The repository card shows a warning when something stops a push from deploying:

• GitHub access was removed or suspended — the app lost access to the repository. Click Reinstall GitHub App and grant access again.
• The last deploy from GitHub did not start — the card shows why, for example a branch or root directory that no longer exists. Fix it in Repository settings, then click Deploy Now.

A build that starts but fails shows up in the deployment history like any other failed deploy.

GitHub App or GitHub Actions?

Both deploy to the same resource; pick one per resource so pushes do not deploy twice.

Next steps

• Deploying from GitHub Actions
• Self-driving (Beta) — fixes arrive as pull requests, and merging one deploys it through this connection
• Deploying a frontend