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.
This guide sets the integration up in the Pipecat Cloud dashboard . 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

In the dashboard, 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.

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

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

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