> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/integrations/source-control/github.md). # GitHub The GitHub integration lets codev work with your repositories — reading code, opening and updating pull requests, posting check results, and acting on behalf of individual contributors for Git operations. You configure it under **Settings > Organization > Integrations > GitHub**. Only organization owners can manage it. ## Authentication methods GitHub supports three authentication methods. They serve different purposes, and you can register more than one. | Method | What you provide | What it powers | | --------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **GitHub App** | App ID and a private key | The recommended way for codev to act on your repositories — clones, pull requests, check runs, and other repository operations. | | **OAuth App (Device Flow)** | A Client ID, and optionally a Client Secret | Lets individual users link their personal GitHub identity to codev through a device login, so Git operations run as that user. The Client Secret is only needed to refresh and revoke those user tokens — starting a device login needs only the Client ID. | {% hint style="info" %} Both methods are backed by a **GitHub App** — they just use different parts of it. The **GitHub App** method uses the app's private key so codev can act as an application on your repositories. The **OAuth App (Device Flow)** method uses the same app's OAuth client credentials so an individual user can authorize codev to act as them. Many teams configure both. {% endhint %} {% hint style="warning" %} **Legacy GitHub OAuth Apps are not supported.** The device-login method uses the OAuth credentials of a **GitHub App** with *Device Flow* enabled — not a classic GitHub "OAuth App". Create or reuse a GitHub App under **GitHub Settings > Developer settings > GitHub Apps**. {% endhint %} ## Signing in to codev uses flxbl's OAuth app This is the most common point of confusion, so it is worth stating plainly. **On the cloud instance, you sign in to codev with social login (for example, "Sign in with GitHub"). That sign-in always uses flxbl's own OAuth app.** It is part of how the cloud service authenticates you, and you cannot replace it. The OAuth App you register here is a **different** thing. It is used to link a contributor's personal GitHub identity for **Git operations inside codev** — and to refresh and revoke those tokens. Registering your own OAuth App does **not** change how you, or anyone on your team, signs in to codev. | Action | Which OAuth app is used | | ------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | Signing in to codev (cloud) | flxbl's OAuth app — always, and not configurable | | Linking your GitHub identity for Git operations (device flow) | Your registered OAuth App if you add one; otherwise the instance's managed OAuth app | {% hint style="warning" %} Adding a GitHub OAuth App integration is about *acting on GitHub as a user*, not about *logging into codev*. If your goal is to change how people authenticate into the product, an integration is not where that happens. {% endhint %} ## On the cloud: you start already connected On the cloud instance, GitHub is already connected through flxbl's installed GitHub App, so codev can work with the repositories you've granted it without any setup. The GitHub page shows this as **connected via the installed App (Cloud mode)**. You add your own GitHub integration on top of that when you want to: * Use your **organization's own GitHub App** instead of the managed one. * Scope a credential to a **specific project**. * Register your **own OAuth App** for user device login and token refresh. When you do, your integration takes precedence following the resolution order below. ## Scoping and precedence Each integration is either **Global (all projects)** or scoped to a **specific project**, and a global integration can be marked as the **default** for GitHub. When codev authenticates for a project, it picks the most specific match: 1. A GitHub integration scoped to **that project** 2. The integration marked **default** for GitHub 3. A **global** GitHub integration 4. The instance's managed GitHub App (on cloud, flxbl's installed App) Repository operations always authenticate with a **GitHub App**. ## Adding an integration 1. Go to **Settings > Organization > Integrations > GitHub**. 2. Under **Add New Integration**, choose the **Authentication Method**. 3. Fill in the credentials for that method: * **GitHub App** — App ID and the contents of the app's private key (`.pem`) file. * **OAuth App (Device Flow)** — the **Client ID** of a GitHub App with *Device Flow* enabled, and its **Client Secret** if you want token refresh and revoke. Legacy GitHub OAuth Apps are not supported. 4. Set **Availability** to **Global** (optionally marking it the default) or to a **specific project**. 5. Click **Add Integration**. Existing integrations are listed with their method, scope, default marker, and status, and can be edited or removed at any time. {% hint style="info" %} **Where to create the GitHub credentials.** GitHub Apps are created under GitHub's **Settings > Developer settings > GitHub Apps**. Both methods draw from a GitHub App — its private key for the GitHub App method, and its OAuth client credentials (with Device Flow enabled) for the OAuth App method. codev only stores the resulting identifiers and keys. {% endhint %} ## Self-hosting On a self-hosted instance there is no managed GitHub App, so you provide the GitHub credentials yourself. Server-level provider configuration is covered in the [sfp server](https://docs.flxbl.io/sfp-server) documentation; the per-project and per-provider integrations on this page work the same way once the server is configured. *** Once the OAuth App is registered, each user links their own GitHub identity so codev can act as them. {% content-ref url="/pages/DsXvZkWNzddlVfOBcXBx" %} [Connected accounts](/flxbl/codev/integrations/connected-accounts.md) {% endcontent-ref %} --- # 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.flxbl.io/flxbl/codev/integrations/source-control/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.