Skip to main content
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

​
Connect your GitHub account

The GitHub App is installed once per Pipecat Cloud organization, and every agent in that organization shares it.
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

Return to the dashboard

Once you approve the install, the dashboard picks up the connection automatically and shows the connected account.
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.

​
Deploy a new agent from a repository

When you create an agent, choose GitHub as the source:
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.
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.
Go to your agent’s Settings → GitHub tab and pick a repository, branch, and Dockerfile path.
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.
Toggle it on the agent’s Settings → GitHub tab.

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

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

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

​
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

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