Skip to main content

GitHub credentials

In order to show and import information about your GitHub repositories and teams, OpenContext needs either a personal access token or GitHub app credentials with the right permissions for your organization. Some of the information that is shown includes:

SaaS customers: these secrets can be uploaded to our Client Portal by your organization's admin user.

Self hosted customers: your admin needs to add configure the token in the app as detailed in our docs.

Personal Access Token​

The GitHub token is used to read information for ALL GitHub orgs provided!
With Github, only personal access tokens (classic) can access the GraphQL API at this time. Fine-grained tokens are not supported.

Create a classic personal access token with the following permissions:

To read software components:

  • repo

To read organization data:

  • read:org
  • read:user
  • user:email

If you have SAML enabled for your GitHub organization you will also need to follow the following steps to grant your token access to your organization.

GitHub app​

Alternately, you can choose to create a GitHub app with the permissions below:

To read software components:

  • Actions: Read-only
  • Checks: Read-only
  • Code scanning alerts: Read-only
  • Commit statuses: Read-only
  • Contents: Read-only
  • Dependabot alerts: Read-only
  • Deployments: Read-only
  • Discussions: Read-only
  • Environments: Read-only
  • Issues: Read-only
  • Metadata: Read-only
  • Packages: Read-only
  • Pages: Read-only
  • Projects: Read-only
  • Pull requests: Read-only
  • Secret scanning alerts: Read-only

To read organization data:

  • Events: Read-only
  • Members: Read-only

To read account data:

  • Email addresses: Read-only
  • Interaction limits: Read-only

Once the application is created you have to generate a private key for the application and place it in a YAML file. The YAML file must include the following information:

  • appId (required) -- Generated for you when you create the GitHub app
  • installationId (required) -- The installationId can be found by going to https://github.com/organizations/YOUR_ORG/settings/installations and clicking on Configure next to the GitHub app. The installation id is at the end of the URL you are sent to. For instance, https://github.com/organizations/YOUR_ORG/settings/installations/12345678 has an installationId of 12345678.
  • clientId (required) -- Generated for you when you create the GitHub app
  • clientSecret (required) -- Generated for you when you create the GitHub app
  • privateKey -- Please note that indentation for privateKey is required!

The YAML file can also include the following optional information:

  • allowedInstallationOwners (optional) -- list of GitHub orgs which can use this GitHub app credential. If this is not specified then all GitHub orgs will use the same credentials.
  • webhookUrl (optional) -- Generated for you when you create the GitHub app
  • webhookSecret (optional) -- Generated for you when you create the GitHub app

Example github-app.yaml

appId: app id
installationId: installation_id_number
allowedInstallationOwners: ['YOUR_GITHUB_ORG']
clientId: client id
clientSecret: client secret
webhookSecret: webhook secret
privateKey: |
  -----BEGIN RSA PRIVATE KEY-----
  ...Key content...
  -----END RSA PRIVATE KEY-----

For more information​

For more information on how we integrate with GitHub, see the following video: