--- title: "Connect GitHub to Rig — Rig guide" description: "Connect a GitHub organisation to Rig with a GitHub App or a fine-grained token, and sync repos, issues, members and pull requests." canonical: "https://rig.so/guides/connect-github" format: markdown --- Search guides, references, playbooks…⌘K Browse guides # Connect GitHub to Rig Rig reads one GitHub organisation and loads its repositories, issues, members and pull requests, with lines added and removed for each pull request. You can sign in as a GitHub App, which is not tied to a person, or with a fine-grained access token. ## Before you start - You need to be an owner of the GitHub organisation to create and install an App. For a token, you need access to the organisation's repositories. - Know the organisation's handle, which is the part after `github.com/` in its address. - This card is for organisations. For repositories under a personal account, use the **GitHub (personal account)** card instead. ## Step 1: Create a GitHub App (recommended) 1. In GitHub, open your organisation's `Settings`, then `Developer settings` → `GitHub Apps` → `New GitHub App`. 2. Name it, deselect webhook **Active** and leave the callback URL empty. Under **Where can this GitHub App be installed?**, choose **Only on this account**, or **Any account** if you will install it on several organisations. 3. Set these permissions to **Read-only**. Repository: Metadata, Contents, Pull requests, Issues, Deployments and Actions. Organization: Members. 4. Create the App. On its page, copy the **App ID** (the number, which differs from the Client ID), then click `Generate a private key` and keep the downloaded `.pem` file. 5. Choose `Install App`, pick your organisation and select all repositories, or only the ones Rig should read. 6. Open the installation's settings. The **Installation ID** is the number at the end of the address, `github.com/organizations//settings/installations/`. ## Step 2: Or create a fine-grained token Use this route if you cannot create an App. The token is tied to the person who creates it. 1. In GitHub, click your profile picture → `Settings` → `Developer settings` → `Personal access tokens` → `Fine-grained tokens` → `Generate new token`. 2. Set **Resource owner** to your organisation, choose the repositories Rig should read and set an expiration. 3. Grant read access to Metadata, Issues and Pull requests, and under Organization permissions grant Members (read). 4. If your organisation requires approval for fine-grained tokens, an owner approves the request before it works. ## Step 3: Connect it in Rig New to Rig? Watch how to find Connections Adding a source needs a workspace owner, or a role with the Manage connections permission, on a workspace where you manage your own connections. If the Connectors tab says “Data ingestion for this workspace is managed by Rig”, ask an owner or Rig support to add the source. 1. In Rig, open `Connections`, choose the `Connectors` tab and go to `Sources & actions`. 2. Search for **GitHub**, open the card and click `Connect`. 3. Enter **GitHub organization**: the handle only, such as `acme`, never a full URL. 4. Pick the **GitHub App** tab or the **Personal access token** tab. 5. For the App, enter **App ID**, **App private key** (paste the whole `.pem` file, including the BEGIN and END lines) and **Installation ID**. 6. For a token, enter **GitHub access token**. 7. Click `Continue`. Rig checks the credentials and lists the streams it can reach, so choose the ones you want and click `Connect`. 8. The source then syncs on its schedule, which is nightly unless you change it. Click `Sync` on its row to load data straight away. ## What Rig pulls in GitHub lands in its own `github` schema in your warehouse: - **Repositories**: every repository the credential can read in the organisation. - **Issues**: issues across those repositories. - **Members**: the organisation's members. - **Pull requests**: pull requests across those repositories. - **Pull request stats**: diff statistics for each pull request, such as lines added and removed. ## Good to know - Rig syncs every repository the credential can read. To limit it, install the App on selected repositories or scope the token to them. - One connection covers one organisation. An App installed on several organisations needs a connection each, with that organisation's own Installation ID. - A GitHub App signs short-lived installation tokens, so nothing depends on one person's account or a paid seat. - With a token, Rig re-pulls all issues in full once a week to find deleted ones. An App connection reads issues repository by repository and cannot detect deleted ones. - Pull request stats makes one call per pull request on every run. Deselect it if you have a very large number of pull requests. - The **GitHub (personal account)** card covers repositories owned by one person. Its token needs Resource owner set to your own account, and it reads repos, issues, pull requests and pull request stats, with no members. Use a fine-grained token limited to selected repositories, since a classic token can read all of yours. - To disconnect GitHub, click the bin icon on the source's row under `Sources & actions`. Only whoever connected the source or a workspace owner can do this, and data already synced stays in the warehouse. ## What people use this for - Measure pull request cycle time and throughput - Track pull request size and code churn - Monitor issue backlog and bug trends - Report on contributors and ownership [More ideas for using GitHub](https://rig.so/integrations/github) ## GitHub documentation - [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) - [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) Was this guide helpful? Yes No --- - [This page as HTML](https://rig.so/guides/connect-github) - [Site map for language models](https://rig.so/llms.txt) - [API and agent documentation](https://rig.so/developers)