Skip to main content

GitHub

CatalogDiscoveryGitOpsScorecardsTeams

Summary

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

Setup

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.

caution

If you do not see the Settings page you're looking for in the sidebar, you likely don't have the proper permissions and need to contact your admin.

caution

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 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.

note

If you are looking to use the GitHub Dependabot rules then you must verify you have the necessary permissions on repositories you'd like to see vulnerabilities on. To verify, navigate to a repository on GitHub and click "Settings" -> "Code security and analysis" and make sure you are a member of a team under "Access to alerts".

caution
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.

Registration

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

Catalog Descriptor

Git

x-cortex-git:
github:
repository: <org>/<repo>
basepath: myService # optional
FieldDescriptionRequired
repositoryorg/repo as defined in GitHubtrue
basepathIf the entity 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.

Ownership

You can define the following block in your Cortex Catalog Descriptor to add your Github teams.

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.

x-cortex-owners:
- type: group
name: cortex/engineering # Must be of form <org>/<team>
provider: GITHUB
description: This is a description for this owner # optional