Skip to main content
This guide shows you how to automate Pipecat Cloud deployments from GitHub Actions using the official Deploy to Pipecat Cloud action.

​
Prerequisites

Before setting up your workflow, ensure you have:
  • A Pipecat Cloud account with a Private API key
  • A secret set configured for your agent

​
Configure GitHub Secrets

Add the following secret to your repository (Settings → Secrets and variables → Actions):
  • PCC_API_KEY: Your Pipecat Cloud Private API key

​
Basic Workflow — Cloud Build

The simplest setup uses cloud builds to build your image server-side. No Docker, no container registry, no extra infrastructure. Create .github/workflows/deploy.yml in your repository: 
name: Deploy to Pipecat Cloud

on:
  push:
    branches: ["main"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build and Deploy to Pipecat Cloud
        uses: daily-co/pipecat-cloud-deploy-action@v2
        with:
          api-key: ${{ secrets.PCC_API_KEY }}
          agent-name: ${{ github.event.repository.name }}
          cloud-build: true
          secret-set: my-secret-set
          region: us-east
This workflow will:
  1. Trigger on every push to the main branch
  2. Create a build context from your repository
  3. Upload it to Pipecat Cloud and build the image server-side
  4. Deploy the new image and wait for readiness
Cloud builds automatically detect and reuse identical build contexts, so re-deploying unchanged code is nearly instant.

​
Build Caching

Cloud builds use a content hash of your build context to detect cache hits. If the files haven’t changed since the last successful build, the action skips the upload and build entirely and reuses the previous image. You can also reuse a specific build across workflows with the build-id input: 
- name: Deploy to Pipecat Cloud
  uses: daily-co/pipecat-cloud-deploy-action@v2
  with:
    api-key: ${{ secrets.PCC_API_KEY }}
    agent-name: ${{ github.event.repository.name }}
    build-id: 14f5a062-7ecd-407a-b5f0-3ebba82e790b
    secret-set: my-secret-set

​
Monorepo Configuration

If your agent lives in a subdirectory (e.g. server/), set the build context and optionally restrict the workflow to that path: 
name: Deploy to Pipecat Cloud

on:
  push:
    branches: ["main"]
    paths:
      - "server/**"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build and Deploy to Pipecat Cloud
        uses: daily-co/pipecat-cloud-deploy-action@v2
        with:
          api-key: ${{ secrets.PCC_API_KEY }}
          agent-name: ${{ github.event.repository.name }}
          cloud-build: true
          build-context: ./server
          dockerfile: Dockerfile
          secret-set: my-secret-set
The paths filter ensures the workflow runs only when files under server/ change.

​
Customizing Deployment

Configure the deployment via action inputs:
  • secret-set: Name of the secret set used for runtime environment variables
  • region: Deployment region (uses your organization default if omitted)
  • min-agents: Minimum agents to keep warm (0–50)
  • max-agents: Maximum concurrent agents (1–50)
  • agent-profile: Agent profile name, if used
  • wait-for-ready: Whether to poll until the deployment is ready (default: true)
  • wait-timeout: Max seconds to wait for readiness (default: 90)
Tune min-agents and max-agents based on your traffic. See the Capacity Planning guide for guidance.

​
Deploying from Your Own Container Registry

If you host images in your own container registry (e.g. Docker Hub, AWS ECR, GHCR), you can skip the cloud build and deploy a fully tagged image directly: 
- name: Deploy to Pipecat Cloud
  uses: daily-co/pipecat-cloud-deploy-action@v2
  with:
    api-key: ${{ secrets.PCC_API_KEY }}
    agent-name: ${{ github.event.repository.name }}
    image: my-registry.example.com/my-agent:v1.2.3
    image-credentials: my-image-pull-secret
    secret-set: my-secret-set
When deploying a pre-built image, you must provide an image-credentials reference if the image is in a private registry. Pipecat Cloud requires images built for linux/arm64.

​
Using v1 with Docker Build

v1 is still available for users who need the action to run docker build and push to their own container registry. However, we recommend upgrading to v2 with cloud builds for a simpler setup.
The v1 action can build, tag, and push Docker images as part of the workflow. This requires registry credentials and the packages: write permission (for GHCR): 
- name: Build and Deploy to Pipecat Cloud
  uses: daily-co/pipecat-cloud-deploy-action@v1
  with:
    api-key: ${{ secrets.PCC_API_KEY }}
    agent-name: ${{ github.event.repository.name }}
    build: true
    image: ${{ secrets.DOCKERHUB_USERNAME }}/${{ github.event.repository.name }}
    registry-username: ${{ secrets.DOCKERHUB_USERNAME }}
    registry-password: ${{ secrets.DOCKERHUB_TOKEN }}
    secret-set: my-secret-set
    image-credentials: my-image-pull-secret
See the v1 README for full documentation of v1 inputs.

​
Next Steps

Secrets Management

Learn how to securely manage image pull secrets and environment variables.

Scaling Configuration

Configure auto-scaling to handle varying traffic loads.