Skip to main content
Connect GitHub when your code lives in GitHub. After a Horizon organization links a GitHub installation, Horizon can list the repositories that installation grants, create hosted servers from those repositories, and start builds when relevant Git events arrive. The boundary is simple: GitHub owns repository access and source history. Horizon owns the server record, build record, deployment URL, environment selection, access policy, and observability once a repository revision is used for a hosted server.

Link repositories

Connect one or more GitHub accounts or organizations to a Horizon organization.

Build from commits

Resolve a selected repository branch to an exact commit before creating a build.

Preview pull requests

Use pull request events to create preview builds and preview deployment URLs.

Keep source access separate

Use GitHub access only for repository discovery and builds. MCP clients do not receive GitHub credentials.

​
When to use GitHub

Use the GitHub integration when the server source lives in GitHub and Horizon should build, deploy, and update a hosted Python MCP or FastMCP server from that source. GitHub works well when:
  • A repository should become a hosted Horizon server.
  • Default branch pushes should create new production-ready builds.
  • Pull requests should create preview builds before production promotion.
  • Operators need the build list to show branch, commit, pull request, and repository context.
  • Repository permissions should stay in GitHub while Horizon manages the deployed MCP endpoint.
If the server already runs outside Horizon and should stay there, register it as an external server. If clients should use a composed endpoint made from multiple servers, create a remix server.

​
Integration contract

A GitHub connection does not make a server public. Hosted server authentication, server access, capability policy, and deployment promotion still follow the hosted-server contract.

​
Connect GitHub

You can connect GitHub from onboarding or from organization settings.
1

Open the GitHub connection flow

During onboarding, Horizon sends users without a linked installation to the GitHub connection step. In an existing organization, open Settings and then Integrations.
2

Authorize or choose an existing installation

Horizon opens a GitHub authorization window. If the signed-in GitHub user already has unlinked Horizon installations available, Horizon asks which account to link. Otherwise, GitHub asks the user to install or configure the Horizon GitHub App.
3

Choose repository access

In GitHub, select the repositories Horizon should be able to see. You can grant access to all repositories in the account or only selected repositories.
4

Return to Horizon

After GitHub redirects back, Horizon verifies the request, links the installation to the organization, and returns to the repository picker or the integrations page that started the flow.
Members and admins can start the GitHub connection flow for an organization. The GitHub user completing the popup must administer the selected GitHub account: the owner for a personal account, or an organization admin for a GitHub organization. Accounts you can see but do not administer appear disabled in the picker. If a GitHub organization installed the app before it requested organization member read access, a GitHub organization admin must accept the updated permissions on GitHub before that organization can be linked to another Horizon organization.

​
Repository picker

The repository picker shows repositories from every GitHub installation linked to the active Horizon organization. Repositories are sorted by recent update time, include public or private visibility, and show the repository default branch. When you select a repository, Horizon carries this information into the hosted server setup form:
  • repository full name
  • repository visibility
  • GitHub installation ID
  • default branch
  • suggested server name
If no GitHub installation is linked, Horizon redirects the repository picker to the GitHub connection flow. If a repository is missing, edit repository permissions from Settings > Integrations, then refresh the picker.

​
Create a hosted server

After selecting a repository, Horizon asks for the server configuration that turns the repository into a hosted MCP endpoint. When you submit the form, Horizon runs through these steps:
1

Fetch repository metadata and default branch

2

Resolve the default branch to a commit

3

Create the server record

4

Create a default branch record

5

Queue the first build

6

Create the first deployment record

7

Run the build in the background

The first build uses the repository default branch at the time Horizon creates the server. Later changes to the default branch create later builds; they do not rewrite the first build.

​
What GitHub events do

Horizon processes GitHub events only when they match a linked installation and a repository already tracked by a hosted server. A repository can back more than one hosted server. On a matching push or pull request event, Horizon queues a build for every hosted server that tracks that repository and branch. In a monorepo, changing files for one server does not currently skip builds for the other matching servers. If a pull request existed before the hosted server was created, Horizon may not create an automatic preview for that older pull request. Create a new pull request after the server exists, or use the dashboard workflow for the revision you want to test.

​
Production and preview behavior

Default branch builds and pull request builds use different deployment contexts. Successful preview builds do not automatically change production traffic. A successful default branch build also does not mean clients changed endpoints; confirm which build the live deployment currently selects on the Deployments page.

​
Repository access and missing source

Repository access can change outside Horizon. The most common symptoms are a missing repository in the picker, a build that cannot read source, or a private repository build that cannot start.
Open Settings > Integrations, choose the GitHub installation, and edit repository permissions in GitHub. After the repository is granted to the installation, refresh the picker.
Confirm the file path is relative to the repository root, does not include parent-directory references, and exists on the selected branch. For an entrypoint with an object name, use server.py:object_name.
Confirm the server was already tracking the repository when the pull request was opened, the pull request branch is still open, and the branch has not been removed from Horizon.
Builds are tied to the commit SHA resolved when the build was queued. Open the build details and compare the recorded commit with the current branch tip.
The installation may have no selected repositories, access may have been removed, or GitHub may not be returning repositories for that installation. Edit permissions from the integrations page and try again.

​
Security boundary

GitHub source access is separate from Horizon endpoint access.
  • GitHub permissions decide which repositories Horizon can discover and build.
  • GitHub installation administration decides who can link an installation: the account owner for a personal account, or an organization admin for a GitHub organization.
  • Horizon organization membership decides who can start the integration flow in Horizon.
  • Server access and capability policies decide who can use the deployed MCP endpoint.
  • Build-time repository access is not returned to MCP clients.
  • Environment variables and secrets are scoped through Horizon deployment settings, not through GitHub repository visibility.
This separation means a user can have access to a deployed Horizon endpoint without having access to the underlying GitHub repository, and a GitHub collaborator does not automatically receive access to the Horizon server.

Hosted servers

Understand the hosted-server contract across source, builds, deployments, gateway access, runtime, and observability.

Build system

See how Horizon packages Python MCP and FastMCP source into build artifacts.

Builds

Review build states, inputs, outputs, and troubleshooting boundaries.

Deployments

Learn how successful builds become live or preview deployment URLs.

Environment variables

Configure production and preview environment variables.

Authentication

Choose how MCP clients authenticate to hosted endpoints.