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, workflow runs)
• Scorecard rules
• Ownership

Setup

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.

Multi-account support

GitHub has multi account support - entities can be tagged across different GitHub organizations, instances, and credentials.

Each GitHub configuration requires an alias, which is a name that we use to correlate the instance you want to use with the application registrations for various entities. There is also a default configuration used by registrations without an alias listed. You can edit aliases and the default configuration under Settings → GitHub.

GitHub App

One option to connect Cortex to your GitHub instance is using the official GitHub app, or your own provided app. You can install the app under Settings → GitHub.

caution

If using Cortex Server, you'll need to submit your own GitHub app, as the offical one will not be available. You can add new apps under Settings → GitHub.

The official 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 that has access to all orgs, or multiple configurations with corresponding aliases.

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.

note

Beyond the minimum permissions indicated above, many scenarios will require that the user who generated the personal access token have organization ownership permissions within GitHub. One such scenario is determing the status of branch protection.

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.
We route our requests through a static IP address. Reach out to support at help@cortex.io to receive details about our static IP. If you're unable to directly whitelist our static IP, you can route requests through a secondary proxy in your network that has this IP whitelisted, and have that proxy route traffic to your GitHub instance.

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
    alias: myApp # optional

Field	Description	Required
repository	org/repo as defined in GitHub	true
basepath	If the entity is in a monorepo (e.g. in a subdirectory), use this field to define the subdir	false
alias	Alias is optional and only relevant if you have opted into multi account support	false

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.

Multiple GitHub organizations are not supported yet for ownership, and we will use the default configuration when fetching teams.

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