> ## Documentation Index
> Fetch the complete documentation index at: https://daily-main.mintlify.site/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>
  Everything here works from the [Pipecat Cloud dashboard <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://pipecat.daily.co) or the CLI — each section shows both. 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.

<Tabs>
  <Tab title="Dashboard">
    <Steps>
      <Step title="Open GitHub settings">
        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>
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    pipecat cloud github connect
    ```

    This opens the same GitHub installation screen and then waits, polling until
    the install lands — there's nothing to paste back into the terminal. Approve
    it in the browser and the command reports the connected account.

    Check it any time:

    ```shell theme={null}
    pipecat cloud github status
    ```
  </Tab>
</Tabs>

<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

<Tabs>
  <Tab title="Dashboard">
    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>
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    pipecat cloud deploy my-agent --repo my-org/my-bot --branch main
    ```

    No image argument: passing `--repo` skips the image build and push entirely.
    Add `--dockerfile-path` if your `Dockerfile` isn't at the repository root, and
    `--subdirectory` to build from a subdirectory.

    The same thing in `pcc-deploy.toml`, where flags win over file values:

    ```toml theme={null}
    agent_name = "my-agent"

    [git]
    repo = "my-org/my-bot"
    branch = "main"
    ```

    Not sure what the App can see?

    ```shell theme={null}
    pipecat cloud github repos
    pipecat cloud github branches my-org/my-bot
    ```
  </Tab>
</Tabs>

Creating the agent builds the branch's current commit and deploys it. `--repo`
applies only at creation — to re-point an agent that already exists, use
`agent link` below.

## Connect an existing agent

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

<Tabs>
  <Tab title="Dashboard">
    Go to your agent's **Settings → GitHub** tab and pick a repository, branch,
    and Dockerfile path.
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    pipecat cloud agent link my-agent --repo my-org/my-bot --branch main
    ```

    Re-run it to re-point an agent at a different repository or branch. Options
    you leave out keep their stored values, so changing the branch won't reset a
    Dockerfile path you set earlier.
  </Tab>
</Tabs>

<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 when you want to control the timing yourself, for example while you're stabilizing a branch.

<Tabs>
  <Tab title="Dashboard">
    Toggle it on the agent's **Settings → GitHub** tab.
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    pipecat cloud agent link my-agent --repo my-org/my-bot --branch main --no-auto-deploy
    ```

    Pass `--auto-deploy` to turn it back on.
  </Tab>
</Tabs>

## Deploy manually

Deploying manually builds 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.

<Tabs>
  <Tab title="Dashboard">
    Use the **Deploy** button on the agent's GitHub settings. 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.
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    pipecat cloud agent deploy my-agent --github
    ```

    Returns as soon as the deploy is queued, printing the branch and commit it
    will build. To follow it instead:

    ```shell theme={null}
    pipecat cloud agent deploy my-agent --github --wait
    ```

    <Warning>
      A zero exit from `--wait` means the deploy was observed and did not fail —
      not that it finished. A deploy still building, or superseded by a newer
      push, also exits 0. See [what `--wait`
      reports](/api-reference/cli/cloud/agent#what-wait-reports) before gating a
      pipeline on it.
    </Warning>
  </Tab>
</Tabs>

## 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. Both the dashboard and the CLI say so rather than leaving you to compare them — the dashboard offers a deploy, and `agent status` names the repository and branch the running commit actually came from.

From the CLI:

```shell theme={null}
pipecat cloud agent status my-agent
```

It reports the linked repository and branch, the Dockerfile path, whether pushes auto-deploy, the running commit, and the latest deploy attempt with its failure reason. `pipecat cloud agent list` carries a GitHub column for agents built from a repository.

## 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, or run `pipecat cloud agent link` again with the new
    values. The running deployment is untouched until the next deploy.
  </Accordion>

  <Accordion title="Unlink one agent">
    **Unlink**, or `pipecat cloud agent unlink my-agent`, 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**, or `pipecat cloud github
            disconnect`, 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 and `pipecat cloud github status` both flag 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. `pipecat cloud github repos` lists exactly what the App can
    currently see.
  </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.
    `pipecat cloud agent status my-agent` shows the connected branch and
    auto-deploy setting; `pipecat cloud github status` flags a suspended
    installation.
  </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>