Skip to main content




GitHub is a Git-based source code repository. You can use GitHub to drive insights into values such as:

  • Git repository details (commit history, contributors
  • Scorecard rules
  • Ownership


GitHub App​

One option to connect Cortex to your GitHub instance is using our official GitHub App. You can install the app under Settings β†’ GitHub.


If using Cortex Server, you'll need to follow a manual configuration process to use the GitHub app. Reach out to the support team to receive instructions.

The GitHub App comes preconfigured with:

  • Permissions for the Service Catalog, Scorecards, and Scaffolder
  • Webhooks to enable GitOps
  • Support for using GitHub Teams as an Ownership Provider

Note: if your GitHub setup involves multiple orgs, please use a Personal Access Token.

Personal Access Token​

You can also use a Personal Access Token to connect to GitHub. You'll need to add the repo and read:org permissions at the minimum.

This is a great option when using Cortex Server or a self-hosted GitHub Enterprise instance, since you can easily define the URL to your GitHub location.

If you’re using a self-hosted instance of GitHub, you’ll need to verify that your Cortex instance is able to reach the GitHub instance. See our IP Whitelist section for more.

Service Registration​

You can use GitHub to define metadata about the service's GitHub repo as well as ownership.

Service Descriptor​


repository: <org>/<repo>
basepath: myService # optional
repositoryorg/repo as defined in GitHubtrue
basepathIf the service is in a monorepo (e.g. in a subdirectory), use this field to define the subdirfalse

The value for repository should be the user/repo as defined in GitHub.


You can define the following block in your Cortex Service Descriptor to add your Github teams to a service.

Team name should be of the form <org>/<team>. Team names are generally converted to lowercase with - separators (Team Name would be cortexapps/team-name) β€” but you can verify your exact name from the permalink in GitHub.

- type: group
name: cortex/engineering # Must be of form <org>/<team>