> For the complete documentation index, see [llms.txt](https://docs.kosmoslabs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kosmoslabs.ai/product-documentation/connecting-github.md). # Connecting GitHub Step-by-step guide to connecting GitHub *** This guide walks you through connecting GitHub to Kosmos. Kosmos connects to GitHub through the **Kosmos GitHub App**. You install the app on your organization and choose exactly which repositories it can see. The app requests read-only permissions and cannot write to your repositories. ### Prerequisites * Permission to install a GitHub App on your organization. In most organizations this is an owner or an admin. If you are not an admin, you can still start the install and GitHub will send it to an owner for approval. * Admin access to Kosmos to configure the integration *** ### Step 1: Start the Connection 1. In Kosmos, navigate to **Settings → Integrations** 2. Find the **GitHub** card and click **Connect** 3. You are redirected to GitHub to install the Kosmos app If you already have a GitHub connection from before Kosmos moved to the GitHub App, the card shows an upgrade prompt instead. See [Upgrading an existing GitHub connection](#upgrading-an-existing-github-connection) below. *** ### Step 2: Choose Your Repositories On the GitHub installation screen, select the account or organization you want to connect, then choose the repository scope: * **All repositories** gives Kosmos read access to every current and future repository in the organization * **Only select repositories** limits Kosmos to the repositories you pick Most teams choose **Only select repositories** and add the repositories that produce the deployments they care about correlating. Review the requested permissions, then click **Install**. All permissions are read-only. For the full list and what each one is used for, see [Integration Permissions](/product-documentation/integration-permissions.md#github). You can change the repository selection at any time in GitHub, under your organization's **Settings → GitHub Apps → Kosmos → Configure**. You do not need to reconnect in Kosmos after changing it. **If your installation needs approval:** when a non-admin starts the install, GitHub holds it pending an owner's approval. Kosmos shows the connection as pending until an owner approves it, then completes automatically. *** ### Step 3: Select Repositories to Sync Once the installation completes, you are returned to Kosmos and the repository picker appears. The picker lists only the repositories included in your installation, so what you see in Kosmos matches what the app can actually access. Select the repositories you want Kosmos to sync and click **Save**. If a repository you previously selected for sync is later removed from the installation in GitHub, Kosmos flags it in your sync configuration rather than failing quietly on the next sync. *** ### Step 4: Confirm Production Branches After repository selection, Kosmos asks you to confirm which branches represent production for each repository. * The detected default branch (usually `main`) is prefilled * Adjust it if your team ships from a differently named branch, such as `develop` * You can add more than one branch per repository This mapping tells Kosmos which deployments reached production, which in turn determines whether a correlation is eligible to become a Risk Event. See [How a correlation becomes a Risk Event](/product-documentation/understanding-results.md#how-a-correlation-becomes-a-risk-event) for why this matters. Kosmos uses the strongest signal available for each deployment event: an explicit environment from the GitHub Deployments API when present, and otherwise your branch mapping. You can revisit the mapping later from **Settings → Integrations → GitHub**. *** ### Step 5: Verify the Connection Once saved, Kosmos begins syncing commits, pull requests, issues, and deployment events from your selected repositories. Navigate to the **Signals** tab to confirm events are flowing in from your connected repositories. *** ### Upgrading an existing GitHub connection If your organization connected GitHub before Kosmos moved to the GitHub App, your existing connection keeps working during a transition period, and the GitHub card in Kosmos shows a prompt to upgrade. Upgrading is worth doing sooner rather than later. The older connection model could not limit access to specific repositories, so upgrading is what narrows Kosmos to the repositories you choose. To upgrade: 1. Go to **Settings → Integrations** and click the upgrade prompt on the **GitHub** card 2. Complete the installation steps above 3. Your previous authorization is revoked automatically once the installation succeeds Your historical GitHub signals, existing correlations, and sync configuration carry over. Repositories that remain in scope keep their production branch mapping. *** ### Revoking Access **From Kosmos:** Settings → Integrations → GitHub → Disconnect **From GitHub:** Your organization's **Settings → GitHub Apps → Kosmos → Uninstall**. Uninstalling the app immediately ends Kosmos's access to every repository in that installation. Because Kosmos authenticates as an installed app rather than holding a long-lived token, removing the installation is sufficient. There is no separate token left active afterward. *** ### Troubleshooting **Connection shows as pending** * An owner still needs to approve the installation. Check your organization's pending GitHub App requests. **A repository is missing from the picker** * The repository is not part of your installation. Add it in GitHub under **Settings → GitHub Apps → Kosmos → Configure**, then return to the Kosmos repository picker. **Integration shows "needs re-authentication"** * The installation was uninstalled or suspended in GitHub. Reinstall the app from the GitHub card in Kosmos. **Deployments are correlating but not treated as production** * Check your production branch mapping in **Settings → Integrations → GitHub**. If a deployment's merge target is not listed as a production branch and GitHub sends no explicit environment, Kosmos treats it as non-production. *** ### Data Access For details on what Kosmos reads from GitHub, see [Integration Permissions](/product-documentation/integration-permissions.md#github). All access is **read-only**. Kosmos never creates, updates, or deletes anything in your repositories. *** **Questions?** Contact | [app.kosmoslabs.ai](https://app.kosmoslabs.ai/) © 2026 Kosmos AI Labs, Inc. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kosmoslabs.ai/product-documentation/connecting-github.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.