> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CI with GitHub Actions

> Automate builds and deploys with the official GitHub Action

This guide shows you how to automate Pipecat Cloud deployments from GitHub Actions using the official [Deploy to Pipecat Cloud](https://github.com/daily-co/pipecat-cloud-deploy-action) 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](./cloud-builds) to build your image server-side. No Docker, no container registry, no extra infrastructure.

Create `.github/workflows/deploy.yml` in your repository:

```yml theme={null}
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

<Tip>
  Cloud builds automatically detect and reuse identical build contexts, so
  re-deploying unchanged code is nearly instant.
</Tip>

## 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:

```yml theme={null}
- 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:

```yml theme={null}
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)

<Tip>
  Tune `min-agents` and `max-agents` based on your traffic. See the [Capacity
  Planning guide](./capacity-planning) for guidance.
</Tip>

## 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:

```yml theme={null}
- 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
```

<Note>
  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`.
</Note>

## Using v1 with Docker Build

<Note>
  **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.
</Note>

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):

```yml theme={null}
- 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](https://github.com/daily-co/pipecat-cloud-deploy-action/tree/v1#readme) for full documentation of v1 inputs.

## Next Steps

<CardGroup cols={2}>
  <Card title="Secrets Management" icon="key" href="../fundamentals/secrets">
    Learn how to securely manage image pull secrets and environment variables.
  </Card>

  <Card title="Scaling Configuration" icon="chart-line" href="../fundamentals/scaling">
    Configure auto-scaling to handle varying traffic loads.
  </Card>
</CardGroup>