Onboard a new customer-owned GitHub App

Create a new dedicated, organization-owned GitHub App during the GitHub Cloud onboarding wizard using the GitHub App Manifest Flow. In the Manifest Flow, Cortex Cloud supplies the GitHub App configuration manifest, GitHub creates the GitHub App in your organization, and Cortex Cloud automatically receives and stores the GitHub App credentials scoped to your tenant.

Prerequisites

• Fulfill the Shared prerequisites
• Confirm that your organization intends to own and manage the GitHub App. Because your organization owns the GitHub App, this path onboards even when organization policy blocks third-party app installations

Permissions

A Customer Owned GitHub App requires the following GitHub App permissions:

• Read access to: Dependabot alerts, actions, actions variables, administration, deployments, discussions, emails, members, metadata, organization actions variables, organization administration, organization secrets, organization self-hosted runners, organization user blocking, packages, repository hooks, secret scanning alerts, secrets, and security events
• Read and write access to: checks, code, commit statuses, issues, organization hooks, and pull requests

Cortex Cloud defines these permissions in the configuration manifest embedded in the GitHub app creation page. Because you own and control the GitHub App, you can adjust these permissions after creation. Downgrading a required permission disables the corresponding Cortex Cloud capability. For the full permission-to-purpose mapping, refer to Reference B: Customer Owned GitHub App permissions. If the permissions were downgraded after creation, restore them before reuse to avoid disabling Cortex Cloud capabilities. Refer to Update Customer Owned GitHub App permissions or resolve integration errors.

Onboarding steps

1. In your Cortex tenant.

   1. Select Settings > Data Sources & Integrations, select + Add New.
   2. Search for GitHub (SaaS), hover over the card and click Add, or Add Another Instance if an instance is already onboarded.
   3. On the Configure account step, select New Customer Owned GitHub App > Authorize. Cortex Cloud redirects you to the GitHub app creation page with the configuration manifest embedded and a pre-filled app name in the form. Cortex-Cloud-{org-name}.
2. On the GitHub app creation page.

   1. Accept the suggested app name or change it. The app name is the only decision required to create the GitHub App. The GitHub App is created as a private app, visible only within your GitHub organization.
   2. Select Create GitHub App. GitHub creates the GitHub App in your organization and takes you to the GitHub App installation page.
   3. On the GitHub App installation page, set the GitHub access scope: All repositories or Only selected repositories, and approve the installation. This GitHub access scope determines which repositories the Customer Owned GitHub App can access; you select which accessible repositories Cortex Cloud scans in a later wizard step.
   4. After you approve the installation, GitHub redirects back to Cortex Cloud.
3. In the onboarding wizard:

   1. Select the repositories Cortex Cloud scans:

      • All current repositories
      • All current and future repositories
      • Specific repositories Manual selection supports up to 20 repositories. If you choose manual selection, select at least one repository.
   2. Select Save to create the integration. Result: The Customer Owned GitHub App exists in your GitHub organization, and the corresponding integration appears in the Cortex Cloud integrations list with the Customer Owned ownership indicator. Cortex Cloud begins scanning the selected repositories according to your Application Security configuration.

Verify and manage integrations

After onboarding, verify the connection and manage your GitHub (SaaS) integration from the integrations list.

Troubleshoot

If a step fails, for example, the temporary code exchange does not complete, Cortex Cloud displays a clear error message with a retry option. Select the retry option to restart the failed step.