Connect GitHub to Rig

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/<org>/settings/installations/<id>.

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

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

GitHub documentation

• Registering a GitHub App
• Managing your personal access tokens