> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usekolaos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Git hosts

A git host is the server that holds your repositories. An organization can connect github.com, GitHub Enterprise hosts, Forgejo hosts and Codeberg, and each workspace then adds repositories from any connected host. Admins manage git hosts under **Organization**, then **Integrations**.

| Host | How KolaOS connects |
| - | - |
| github.com, including GitHub Enterprise Cloud on github.com | The KolaOS GitHub App, installed on your account or organization |
| GitHub Enterprise Server | A KolaOS GitHub App that you create on your server |
| GitHub Enterprise Cloud with data residency (`SUBDOMAIN.ghe.com`) | A KolaOS GitHub App that you create on your tenant |
| Forgejo | An OAuth application that you create on your server, and each member's own account |
| Codeberg | KolaOS's OAuth application on Codeberg, and each member's own account |

## Add a GitHub Enterprise host

You need to be an admin in KolaOS and an owner of the organization on your GitHub host that will own the app. The host must answer from the internet, because KolaOS reaches it from the Cloudflare network.

**1. Enter the host**

Choose **Add integration**, then **GitHub Enterprise**. Enter the host URL, e.g. `https://github.acme.com` or `https://acme.ghe.com`, and the organization on that host that will own the app. KolaOS checks that the host answers and shows its version.

**2. Create the app**

Choose **Create app on** your host. Your GitHub host opens with the app's name and permissions filled in. Create the app there, and GitHub returns its ID and key to KolaOS, which stores the key encrypted.

**3. Install the app**

Install the app on the organization and choose the repositories it may access. KolaOS confirms that your account can reach the installation, and the host appears under **Git hosts** as connected.

The app asks for these permissions: contents and pull requests to write, issues to write, checks and commit statuses to read, and metadata to read.

If the setup stops after the app is created, the host shows **Setup incomplete**, and **Resume** opens the install page again.

## Use a repository from the host

Add the repository to a workspace from **Repositories**, where the picker groups repositories by host. Workstations clone it with a token from that host's installation, limited to the workspace's repositories on that host, and `gh` works in the repository without `gh auth login`.

## Add a Forgejo host or Codeberg

Forgejo has no app that KolaOS can install, and its access tokens can do anything their user can do. KolaOS therefore never shares one token with the whole organization. Each member links their own account, and a workstation gets only its owner's token.

**1. Enter the host**

Choose **Add integration**, then **Forgejo**, and enter the host URL. KolaOS checks that the host answers and shows its version. For Codeberg, choose **Codeberg** and **Add Codeberg**.

**2. Create the OAuth application**

On your Forgejo host, open **Settings**, then **Applications**, and create an OAuth2 application with the redirect URI that KolaOS shows. Paste its client ID and client secret into KolaOS. Codeberg needs no application of your own.

**3. Link your account**

Choose **Link your account** and allow KolaOS on your Forgejo host. Every member does this once under **Account**, then **Git hosts**.

The host page lists which members linked an account. A member who hasn't linked one sees a message on **Repositories**, and `git` in their workstation prints the same message: "Link your account on HOST in KolaOS to clone and push REPOSITORY."

Workstations have `tea`, the Forgejo command line tool, signed in with the member's linked account, so agents open pull requests with `tea pr create` and read them with `tea pr`. A member who hasn't linked an account gets the link message from `tea` too.

## Remove a host

Open the host and choose **Remove**. KolaOS removes the host's repositories from every workspace. On a GitHub host it also deletes its copy of the app's key and uninstalls the app, and the app itself stays on your host, where you can delete it in the organization's settings. On a Forgejo host it deletes every member's token and its copy of the OAuth secret. Removing a member from the organization also deletes their tokens.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.