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

AreaWhat users can expect
ConnectionA Horizon organization can link one or more GitHub installations. Each installation belongs to a GitHub user or organization account.
Repository listHorizon lists repositories that the linked installation grants. Repositories outside the installation permission set do not appear in the picker.
Source selectionCreating a hosted server stores the selected repository, its GitHub repository ID, full name, default branch, entrypoint, and dependency file setting.
Build revisionHorizon resolves a branch or pull request to a commit SHA before build work begins. Moving the branch later does not change that build.
CredentialsHorizon uses repository access for discovery and build checkout. GitHub credentials are not exposed to MCP clients.
EventsPush, pull request, branch deletion, installation, and repository-permission events update Horizon records when they match a linked installation and tracked repository.
RemovalRemoving repository access or deleting the installation can make repositories unavailable to Horizon. Builds that need unavailable source access cannot proceed until access is restored.
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 also have permission in GitHub to install or link the selected account.

​
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.
FieldBehavior
Server nameDetermines the Horizon server name and the deployment slug preview.
EntrypointPoints to the Python file, and optional object name, that defines the MCP server. Horizon validates the path format and can check that the file exists in the selected branch.
AuthenticationHorizon authentication is enabled by default. Disabling it is available only when the organization plan allows it.
Dependency fileOptional. Use it when dependencies are not in the file Horizon would otherwise discover.
Environment variablesOptional KEY=value lines. Names must use uppercase letters, numbers, and underscores, and must start with a letter or underscore.
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.
EventHorizon behavior
Default branch pushCreates a queued build and deployment record for the tracked default branch, unless the same commit already has a build for that server and branch.
Non-default branch pushCreates a preview build only when Horizon is already tracking that branch for an open pull request.
Pull request opened or reopenedCreates a branch record, queued build, and preview deployment for each matching hosted server.
Pull request synchronizedCreates a new queued build and preview deployment for the updated pull request head commit.
Pull request closed without mergeRemoves the preview branch record for the matching server and repository.
Branch deletedRemoves the matching branch record from Horizon.
Repository access addedMakes the repository available to linked Horizon organizations after repository data refreshes.
Repository access removedRemoves the repository from Horizon’s authorized source records and starts cleanup for related deployment resources.
Installation deletedRemoves the linked installation record from Horizon.
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.
ContextSourceEnvironment scopeDeployment behavior
Production candidateThe tracked default branch commit.Production variables.The build can become the live deployment through the production deployment workflow.
Pull request previewThe pull request head commit.Preview variables plus branch-specific overrides.Horizon creates or updates a preview deployment URL for that branch.
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.
  • 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, preview, and branch-scoped values.

Authentication

Choose how MCP clients authenticate to hosted endpoints.