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

# Deploy from GitHub

> Connect the Pipecat Cloud GitHub App to deploy agents from a repository branch, with deploy on push, manual deploys, and commit tracking.

Connect a GitHub repository to an agent and Pipecat Cloud builds and deploys it for you. Push to the connected branch and your agent updates — no Docker build, no registry, no CI workflow to maintain.

<Info>
  This guide sets the integration up in the [Pipecat Cloud dashboard <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://pipecat.daily.co). Deploys use [cloud builds](/pipecat-cloud/guides/cloud-builds) under the hood, so your project needs a `Dockerfile`.
</Info>

<Note>
  Not sure this is the right method? The [deployment
  overview](/pipecat-cloud/fundamentals/deploy#choosing-a-deployment-method)
  compares the GitHub integration with CLI cloud builds, GitHub Actions, and
  your own container registry.
</Note>

## Prerequisites

* A [Pipecat Cloud account](/pipecat-cloud/fundamentals/accounts-and-organizations) with an active organization
* A GitHub repository containing your agent, with a `Dockerfile` at the repository root (or at a path you specify)
* Permission to install a GitHub App on the account or organization that owns the repository

## Connect your GitHub account

The GitHub App is installed once per Pipecat Cloud organization, and every agent in that organization shares it.

<Steps>
  <Step title="Open GitHub settings">
    In the dashboard, go to **Settings → GitHub**.
  </Step>

  <Step title="Install the app">
    Click **Connect GitHub**. A new tab opens GitHub's installation screen,
    where you choose the account or organization to install into and which
    repositories to grant access to — all of them, or a hand-picked list.
  </Step>

  <Step title="Return to the dashboard">
    Once you approve the install, the dashboard picks up the connection
    automatically and shows the connected account.
  </Step>
</Steps>

<Tip>
  Granting access to only the repositories you deploy from is the safer default.
  You can change the selection later from **Manage on GitHub** without
  reconnecting.
</Tip>

## Deploy a new agent from a repository

When you create an agent, choose **GitHub** as the source:

<Steps>
  <Step title="Pick the repository">
    Select any repository the installation can see. Private repositories are
    supported.
  </Step>

  <Step title="Pick the branch">
    The repository's default branch is preselected. Search to find any other
    branch.
  </Step>

  <Step title="Set the Dockerfile path (optional)">
    Defaults to `Dockerfile` at the repository root. Set a path such as
    `docker/Dockerfile` if yours lives elsewhere.
  </Step>
</Steps>

Creating the agent builds the branch's current commit and deploys it.

## Connect an existing agent

Agents that already run a Docker image can be moved onto GitHub deploys at any time.

Go to your agent's **Settings → GitHub** tab and pick a repository, branch, and Dockerfile path.

<Note>
  Linking a repository does not deploy anything. The agent keeps serving its
  current image until the next push to the connected branch, or until you deploy
  manually. This lets you connect a repository and choose your moment.
</Note>

## Deploy on push

**Deploy on push** is on by default. With it enabled, every push to the connected branch builds that commit and rolls it out.

Pushes to any other branch are ignored — only the branch you connected triggers a deploy.

Turn it off from the agent's **Settings → GitHub** tab when you want to control the timing yourself, for example while you're stabilizing a branch.

## Deploy manually

The **Deploy** button on the agent's GitHub settings builds and deploys the connected branch's current `HEAD`. It works whether or not deploy on push is enabled, and it's the way to ship a change when it's off.

Deploys are queued: the button returns as soon as the build is accepted, and progress shows up in the agent's deployment history and on the [Builds](/pipecat-cloud/guides/cloud-builds) page.

## See what's running

An agent deployed from GitHub shows its source and the exact commit it is running — on the agent overview and in the agents list — linked back to that commit on GitHub.

The commit that's running and the branch that's connected can legitimately differ: right after you link a repository, after you re-point an agent at a different repository or branch, or when deploy on push is off and there are unshipped commits. The dashboard says so and offers a deploy when that's the case.

## Change or remove a connection

<AccordionGroup>
  <Accordion title="Switch branch or repository">
    Edit the repository, branch, or Dockerfile path on the agent's **Settings →
    GitHub** tab and save. The running deployment is untouched until the next
    deploy.
  </Accordion>

  <Accordion title="Unlink one agent">
    **Unlink** removes the agent's connection to the repository. Pushes stop
    deploying it, and its current deployment stays live.
  </Accordion>

  <Accordion title="Disconnect the organization">
    **Disconnect** on **Settings → GitHub** removes the installation and every
    repository link in the organization. Connected agents stop auto-deploying
    and keep running what they last deployed. This does not uninstall the app on
    GitHub — do that from GitHub if you want to revoke access entirely.
  </Accordion>
</AccordionGroup>

## Things to know

* **One agent per repository and branch.** A given repository and branch pair can be connected to a single agent. Use a different branch, or a different repository, for a second agent.
* **Each agent connects to one branch.** To run staging and production from one repository, create two agents and connect each to its own branch.
* **A `Dockerfile` is required.** The build follows the same path as [cloud builds](/pipecat-cloud/guides/cloud-builds). Run `pipecat init` to scaffold a project that already has one.
* **Secrets are configured in Pipecat Cloud**, not in your repository. See [Secrets](/pipecat-cloud/fundamentals/secrets).
* **A suspended installation stops deploys.** If the app is suspended on GitHub, the dashboard flags it; reinstate it from GitHub to resume.

## Troubleshooting

<AccordionGroup>
  <Accordion title="A repository is missing from the picker">
    The installation can only see repositories you granted it. Open **Settings →
    GitHub → Manage on GitHub** and add the repository to the installation's
    access list.
  </Accordion>

  <Accordion title="A push didn't deploy">
    Check that the push went to the connected branch, that **Deploy on push** is
    enabled on the agent, and that the installation isn't suspended on GitHub.
  </Accordion>

  <Accordion title="The build failed">
    Build logs are on the agent's deployment history. The most common causes are
    a `Dockerfile` path that doesn't match the repository and a build that
    succeeds locally but not from a clean checkout — check that everything the
    build needs is committed.
  </Accordion>
</AccordionGroup>