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.

Everything here works from the Pipecat Cloud dashboard or the CLI — each section shows both. Deploys use cloud builds under the hood, so your project needs a Dockerfile.

Not sure this is the right method? The deployment overview compares the GitHub integration with CLI cloud builds, GitHub Actions, and your own container registry.

Prerequisites

• A Pipecat Cloud account 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, or an owner of that organization who can approve your request to install it

Connect your GitHub account

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

Dashboard

1. Open GitHub settings

   Go to Settings → GitHub.

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

3. Authorize Pipecat Cloud

   GitHub returns you to the dashboard, which sends you back to GitHub to authorize the Pipecat Cloud app. This lets Pipecat Cloud confirm that you are the GitHub user who installed it. GitHub asks every time you connect: Pipecat Cloud uses the authorization once and then revokes it.

4. Return to the dashboard

   The tab shows GitHub connected, and the settings page picks up the connection and shows the connected account.

CLI

pipecat cloud github connect

This opens the same GitHub installation screen and then waits until the organization is connected — there’s nothing to paste back into the terminal. After the install, GitHub returns you to the Pipecat Cloud dashboard to authorize the app and finish. If the dashboard asks you to sign in, sign in as the same Pipecat Cloud user the CLI is logged in as. The command then reports the connected account.

Check it any time:

pipecat cloud github status

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.

Link an existing installation

Some installations don’t start from Pipecat Cloud:

• A request an owner approved. If you’re a member of a GitHub organization without permission to install apps, GitHub offers Request instead of Install and asks an owner to approve. Pipecat Cloud doesn’t link the installation when they approve it.
• An install made from GitHub. Installing the app from GitHub directly, rather than from Connect GitHub, doesn’t link it either.
• A disconnected installation. After you disconnect, the app stays installed on GitHub.

Link these to your organization from Pipecat Cloud:

Dashboard

1. Start the link

   Go to Settings → GitHub and click Link existing installation.

2. Authorize Pipecat Cloud

   GitHub asks you to authorize the Pipecat Cloud app, as it does when you connect.

3. Confirm the installation

   The dashboard lists the installations you can link. Click Link on the one you want. It asks you to confirm even when there’s only one.

CLI

pipecat cloud github connect --existing

This opens GitHub’s authorization screen, then the dashboard, where you confirm the installation to link. The command waits until the organization is connected.

An installation can be linked by:

• the GitHub user who installed the app or asked for it, while they’re still a member of the GitHub organization it’s on
• an owner of the GitHub organization or personal account it’s on

Two kinds of installation can only be linked by an owner:

• One with no record of who installed it, most often one connected before Pipecat Cloud began recording that. Only an owner of the GitHub organization can link it.
• One linked to a different Pipecat Cloud organization before. Only an owner of the GitHub organization or personal account can link it here.

You also need access on GitHub to at least one of the repositories the installation covers. If your GitHub organization uses single sign-on, sign in to it on GitHub first. If the person who can link it isn’t in your Pipecat Cloud organization, invite them.

The GitHub app asks for read access to your GitHub organization’s members, so Pipecat Cloud can check who may link an installation. An installation made before the app asked for this can’t be linked until an owner of the GitHub organization approves the updated permissions, on GitHub in the organization’s settings under GitHub Apps. Link existing installation names any installation waiting for that approval.

Deploy a new agent from a repository

Dashboard

When you create an agent, choose GitHub as the source. If your organization isn’t connected to GitHub yet, the form offers Connect GitHub and Link existing installation in place.

1. Pick the repository

   Select any repository the installation can see. Private repositories are supported.

2. Pick the branch

   The repository’s default branch is preselected. Search to find any other branch.

3. Set the Dockerfile path (optional)

   Defaults to Dockerfile at the repository root. Set a path such as docker/Dockerfile if yours lives elsewhere.

CLI

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:

agent_name = "my-agent"

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

Not sure what the App can see?

pipecat cloud github repos
pipecat cloud github branches my-org/my-bot

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.

Dashboard

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

CLI

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.

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.

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.

Dashboard

Toggle it on the agent’s Settings → GitHub tab.

CLI

pipecat cloud agent link my-agent --repo my-org/my-bot --branch main --no-auto-deploy

Pass --auto-deploy to turn it back on.

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.

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

CLI

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:

pipecat cloud agent deploy my-agent --github --wait

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 before gating a pipeline on it.

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:

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

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.

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.

Disconnect the organization

Disconnect on Settings → GitHub, or pipecat cloud github disconnect, stops Pipecat Cloud using the installation and removes 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. To reconnect the same installation later, link it.

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. Run pipecat init to scaffold a project that already has one.
• Secrets are configured in Pipecat Cloud, not in your repository. See 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

An owner approved my request, but nothing connected

Approving a request installs the app without linking it. Whoever asked for it, while still a member of the GitHub organization, or an owner, links it with Link existing installation or pipecat cloud github connect --existing. See Link an existing installation.

Linking was refused

The dashboard says why and what to do. The most common reasons:

• Someone else needs to link this. Only the GitHub user who installed it or asked for it, while still a member of the GitHub organization, or an owner of the GitHub account, can link it.
• Ask a GitHub organization owner. Pipecat Cloud has no record of who installed it, so only an owner of the GitHub organization can link it.
• Ask an owner to link this. It was linked to a different Pipecat Cloud organization before, so only an owner of the GitHub organization or personal account can link it here.
• Nothing to link. GitHub shows you no installation. Check that the app is still installed on the GitHub account, that you’re signed in to GitHub as the right account, that you can access one of the repositories it covers, and that you’ve signed in to single sign-on if your organization uses it.
• Approve the updated permissions. An owner of the GitHub organization needs to approve the app’s read access to members, on GitHub in the organization’s settings under GitHub Apps. Then start again.
• Already linked elsewhere. It’s linked to a different Pipecat Cloud organization. Once it’s disconnected there, an owner of the GitHub account can link it here.

When someone else needs to link it, ask them to use Link existing installation, after inviting them to your Pipecat Cloud organization if they aren’t in it. If that’s you and your GitHub organization uses single sign-on, sign in to it on GitHub, then start again.

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.

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.

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.