Deploying from GitHub Actions

Make every push to main deploy your app. About five minutes to set up, one file to add.

The idea: deploy once from your computer, then let GitHub repeat it. That first deploy answers all the questions — which project, what to call it, how to build it — and writes the answers into a pb.json file. GitHub just re-runs the same command.

Step 1 — Deploy once from your computer

In the folder you want to deploy:

pb cloud login
pb cloud frontend deploy

Use pb cloud pb deploy for a PocketBase instance, or pb cloud backend deploy for a backend. If you have no project yet, run pb cloud project create my-app first.

It will ask you a few things — which project, what to name this. Answer them; this is the only time anyone has to.

If it asks about an env file, choose “Don’t push env vars.” Your .env is almost certainly not committed to git, so GitHub would not find it and the deploy would fail. There is a better place for secrets — see Step 6.

When it finishes, commit the file it wrote:

git add pb.json
git commit -m "Link this folder to PocketBase Cloud"

That file is what makes the GitHub side need no options at all.

Step 2 — Copy your access token

GitHub has no browser to log in with, so it needs a token instead.

In the portal, go to Account → CLI access token → Copy.

Step 3 — Save the token in GitHub

In your repository: Settings → Secrets and variables → Actions → New repository secret.

Name: PB_TOKEN
Secret: paste the token

The name has to be exactly PB_TOKEN.

Step 4 — Add the workflow file

Create .github/workflows/deploy.yml:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm install -g @pocketbasecloud/[email protected]

      - name: Deploy
        # The folder holding pb.json. Use "." if it is at the repo root.
        working-directory: web
        env:
          PB_TOKEN: ${{ secrets.PB_TOKEN }}
        run: pb cloud frontend deploy --no-input

Two things to change: working-directory, and frontend if you are deploying something else (pb or backend).

--no-input is the only flag you need. It tells pb to fail with a clear message instead of waiting for an answer nobody is there to give.

Step 5 — Push

git add .github/workflows/deploy.yml
git commit -m "Deploy on push"
git push

Watch it run under the Actions tab. The deploy prints each step — building, uploading, provisioning — and the URL at the end. If the deploy fails, the job fails; you do not have to check anything yourself.

That’s it. Every push to main now deploys.

Step 6 — If your app needs secrets

PocketBase instances and backends can hold environment variables. Set them once from your computer and GitHub will leave them alone:

pb cloud env set 'STRIPE_KEY=sk_live_…' --target backend --name my-api

They live on the platform, encrypted, and survive every redeploy. Quote the whole KEY=VALUE so your shell does not split it.

Frontends are different: their variables are baked in when the site is built, so they belong in the build step, not on the platform.

      - name: Build
        working-directory: web
        env:
          VITE_API_URL: https://my-api.pocketbasecloud.com
        run: |
          npm ci
          npm run build

      - name: Deploy
        working-directory: web
        env:
          PB_TOKEN: ${{ secrets.PB_TOKEN }}
        run: pb cloud frontend deploy --skip-build --no-input

--skip-build tells pb to upload what you just built instead of building again.

If something goes wrong

Message	What it means	Fix
`Not authenticated. Run 'pb cloud login'.`	GitHub could not use the token	Check the secret is named exactly `PB_TOKEN` and that the `env:` block is on the deploy step. If it worked before, the token expired — copy a new one (Step 2).
`No project selected. Pass --project…`	`pb` could not find `pb.json`	Is `working-directory` right? Did you commit `pb.json` (Step 1)?
`Pass --name to create the first frontend.`	Same cause	As above — or add `--name my-site` to the command.
`Env file not found: .env`	`pb.json` names a `.env` that is not in git	Delete the `"envFile"` line from `pb.json`, and use Step 6 instead.
`Build failed (npm run build exited 1)`	Your build broke, not the deploy	Run the same command locally; it will fail there too.
`Input required but running non-interactively`	Something needed an answer	The line above it says what. Usually a missing `--name`.
`This action needs confirmation. Pass --yes`	You are deleting something	Add `--yes`.
`Backend deployments require a Pro plan`	Plan limit	Backends need Pro. Free and Starter get 1 PocketBase and 5 frontends.
`This project has 2 computes — pass --compute`	Pro account with more than one compute	Run `pb cloud compute ls` and add `--compute <id>`.

Nothing at all happened? GitHub only runs the workflow when the file is on the branch you pushed to, at exactly .github/workflows/deploy.yml, and only for the branches listed under on:.

Two things not to do

Don’t paste the token into the workflow file. It belongs in Secrets. A workflow file is in your repository, and anyone who can read the repository can read it.
Don’t print a PocketBase instance’s details in a workflow. pb cloud pb info and pb cloud pb deploy --json both include the instance’s admin password, and anything a workflow prints can be read by everyone who can see the run. The plain pb cloud pb deploy in Step 4 is safe: it shows the password only the once, when the instance is first created — which you did on your own computer.

Going further

Staging and production from the same folder, deploying several things in order, preview deploys on pull requests, exit codes, and every error message with its cause: the CI/CD reference.