Deploy with GitHub Actions

Keep your automation in GitHub and use GitHub Actions to publish it to Browserbase: Push or merge to main → run the workflow → publish a Function version. This guide uses the Browse CLI to deploy from your repository. It doesn’t connect or continuously sync a repository in the Browserbase dashboard. The workflow publishes code; it doesn’t invoke your automation or set up a schedule.

Prerequisites

A GitHub repository with Actions enabled and permission to add an Actions secret.
A standalone npm Function project at the repository root, with package.json, package-lock.json, and index.ts committed. Start with the Functions quickstart if you don’t have a Function yet.
A Browserbase API key for the project you want to deploy to. Browserbase resolves the project from this key; you don’t need to supply a Project ID or log in interactively.
Any runtime Secrets and extensions required by your Function configured in that project.

This recipe uses Node.js 24 and pins browse to 0.11.3, which requires Node.js 22.18 or later. Workspace builds and private package registries are outside this standalone npm recipe.

Prepare the project

From the Function project directory, add the CLI as an exact development dependency:

npm install --save-dev --save-exact browse@0.11.3

Commit package.json and package-lock.json with your Function source. The workflow uses npm ci to install the locked dependencies and npx --no-install to use that installed CLI. Keep the CLI version and lockfile in sync when upgrading. Keep .env and other credential files out of Git. Don’t copy credentials into your Function source or workflow YAML.

If your existing project uses pnpm, keep its dependency management consistent. This npm recipe assumes a standalone project with an npm lockfile; don’t add a second package manager’s lockfile just for CI.

Add the deployment secret

In your GitHub repository, open Settings → Secrets and variables → Actions, select New repository secret, and create BROWSERBASE_API_KEY with the key for your destination Browserbase project. See GitHub’s secret setup instructions. The GitHub secret authenticates deployment. It isn’t automatically available inside a deployed Function. If your handler reads context.secrets, create and attach those Browserbase Secrets separately. Attached Secrets remain attached when you publish a new version of the same Function.

Add the workflow

Create .github/workflows/deploy-functions.yml:

name: Deploy Browserbase Functions

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: browserbase-functions-deploy
  cancel-in-progress: false

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Check out source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: '24'
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Publish Functions
        env:
          BROWSERBASE_API_KEY: ${{ secrets.BROWSERBASE_API_KEY }}
        run: |
          if [ -z "$BROWSERBASE_API_KEY" ]; then
            echo "::error::Add the BROWSERBASE_API_KEY Actions secret before deploying."
            exit 1
          fi
          npx --no-install browse functions publish index.ts

This recipe pins the action commit SHAs and CLI version to make dependency updates explicit. Review and update these pins as part of maintaining the workflow. Pushes to main, including merged pull requests, deploy automatically. To publish manually, open Actions → Deploy Browserbase Functions → Run workflow and select main. Manual runs on another branch skip the deployment job. This example doesn’t deploy from pull request events or make deployment credentials available to them. The concurrency group permits one deployment job at a time without canceling an active publish. GitHub can replace an older pending run with a newer one; this is deployment of the latest queued code, not a guarantee that every commit is deployed. See GitHub workflow concurrency.

Use a self-contained subfolder

If the complete npm Function project lives in functions/, add this under the deploy job:

    defaults:
      run:
        working-directory: functions

Also set cache-dependency-path: functions/package-lock.json in the setup-node step’s with block. Keep index.ts, package.json, the lockfile, and all imported source inside that folder. The CLI packages the current working directory; pointing at an entrypoint elsewhere doesn’t change the upload root. This adjustment doesn’t make a workspace or monorepo build self-contained.

Verify a deployment

The publish command waits for the remote build. A successful build prints its build ID and builtFunctions, including Function IDs and the versions created. A failed build or a polling timeout fails the workflow.

Open the GitHub Actions run for your commit and check Publish Functions.
Open Functions in the Browserbase dashboard and confirm the new build and version.
Keep using the same Function ID for callers. Publishing the same Function name in the same project creates a new version; changing the name creates a different Function.

A successful deployment verifies the build, not the behavior of your automation. Use the invocation guide to run a deliberate test with safe inputs, wait for a terminal status, and check the returned result. Invoking a Function creates a browser session and can perform the actions in your handler, so this workflow doesn’t invoke it automatically. Keep source changes in Git. Editing and publishing the same Function through the Playground can cause the deployed version to differ from your repository until the next CI deployment.

Troubleshooting

Symptom	Check
Missing-key error	Add `BROWSERBASE_API_KEY` under Actions secrets and confirm repository access to any organization secret.
Authentication or authorization failure	Confirm the key is valid and belongs to the intended Browserbase project. Don’t print the key while debugging.
`npm ci` fails	Commit an up-to-date `package-lock.json` alongside `package.json`; reproduce with `npm ci` locally. Ensure its package download URLs are accessible from CI and the remote builder, rather than a local-only registry.
Entrypoint or import not found	Check the job’s working directory, `index.ts`, imported files, and `.gitignore`. The upload root must contain the whole Function project.
Remote build fails	Inspect the build logs in the Browserbase dashboard. Check dependencies and Functions limits; this recipe doesn’t configure private registries or workspaces.
Workflow times out or loses its connection	Inspect the existing remote build before retrying. A client timeout doesn’t cancel a server build, and it may still finish after the GitHub job ends. Resolve that build before another publish.
Deployment succeeds but the Function fails when invoked	Inspect invocation logs, parameters, runtime Secret attachments, and required extensions. Deployment credentials are separate from runtime credentials.

Recover from a code regression

Revert the code change on main, keeping the same Function name, then let the workflow publish the restored code as another version. Confirm the new build in the dashboard before running the workflow’s callers again. This republishes source; it doesn’t undo external actions or data changes made by earlier invocations.

Deploy a Function

Publish from your local project or the Playground.

Invoke a Function

Run deployed code and inspect its result.

Welcome

Platform

Use cases

Optimization

Account

Prerequisites

Prepare the project

Add the deployment secret

Add the workflow

Use a self-contained subfolder

Verify a deployment

Troubleshooting

Recover from a code regression

Deploy a Function

Invoke a Function

​Prerequisites

​Prepare the project

​Add the deployment secret

​Add the workflow

​Use a self-contained subfolder

​Verify a deployment

​Troubleshooting

​Recover from a code regression

Deploy a Function

Invoke a Function

Prerequisites

Prepare the project

Add the deployment secret

Add the workflow

Use a self-contained subfolder

Verify a deployment

Troubleshooting

Recover from a code regression