Edit

Quickstart: Connect your GitHub Environment to Microsoft Defender for Cloud

  • Article

In this quickstart, you will connect your GitHub organizations on the Environment settings page in Microsoft Defender for Cloud. This page provides a simple onboarding experience to auto-discover your GitHub repositories.

By connecting your GitHub organizations to Defender for Cloud, you extend the security capabilities of Defender for Cloud to your GitHub resources. These features include:

  • Foundational Cloud Security Posture Management (CSPM) features: You can assess your GitHub security posture through GitHub-specific security recommendations. You can also learn about all the recommendations for GitHub resources.

  • Defender CSPM features: Defender CSPM customers receive code to cloud contextualized attack paths, risk assessments, and insights to identify the most critical weaknesses that attackers can use to breach their environment. Connecting your GitHub repositories will allow you to contextualize DevOps security findings with your cloud workloads and identify the origin and developer for timely remediation. For more information, learn how to identify and analyze risks across your environment

Prerequisites

To complete this quickstart, you need:

  • An Azure account with Defender for Cloud onboarded. If you don't already have an Azure account, create one for free.

  • GitHub Enterprise with GitHub Advanced Security enabled for posture assessments of secrets, dependencies, IaC misconfigurations, and code quality analysis within GitHub repositories.

Availability

Aspect Details
Release state: General Availability.
Pricing: For pricing, see the Defender for Cloud pricing page.
Required permissions: Account Administrator with permissions to sign in to the Azure portal.
Contributor to create the connector on the Azure subscription.
Organization Owner in GitHub.
GitHub supported versions: GitHub Free, Pro, Team, and Enterprise Cloud
Regions and availability: Refer to the support and prerequisites section for region support and feature availability.
Clouds: Commercial
National (Azure Government, Microsoft Azure operated by 21Vianet)

Note

Security Reader role can be applied on the Resource Group/GitHub connector scope to avoid setting highly privileged permissions on a Subscription level for read access of DevOps security posture assessments.

Connect your GitHub account

To connect your GitHub account to Microsoft Defender for Cloud:

  1. Sign in to the Azure portal.

  2. Go to Microsoft Defender for Cloud > Environment settings.

  3. Select Add environment.

  4. Select GitHub.

    Screenshot that shows selections for adding GitHub as a connector.

  5. Enter a name (limit of 20 characters), and then select your subscription, resource group, and region.

    The subscription is the location where Defender for Cloud creates and stores the GitHub connection.

  6. Select Next: select plans. Configure the Defender CSPM plan status for your GitHub connector. Learn more about Defender CSPM and see Support and prerequisites for premium DevOps security features.

    Screenshot that shows plan selection for DevOps connectors.

  7. Select Next: Configure access.

  8. Select Authorize to grant your Azure subscription access to your GitHub repositories. Sign in, if necessary, with an account that has permissions to the repositories that you want to protect.

    After authorization, if you wait too long to install the DevOps security GitHub application, the session will time out and you'll get an error message.

  9. Select Install.

  10. Select the organizations to install the GitHub application. It is recommended to grant access to all repositories to ensure Defender for Cloud can secure your entire GitHub environment.

    This step grants Defender for Cloud access to the selected organizations.

  11. For Organizations, select one of the following:

    • Select all existing organizations to auto-discover all repositories in GitHub organizations where the DevOps security GitHub application is installed.
    • Select all existing and future organizations to auto-discover all repositories in GitHub organizations where the DevOps security GitHub application is installed and future organizations where the DevOps security GitHub application is installed.

  12. Select Next: Review and generate.

  13. Select Create.

When the process finishes, the GitHub connector appears on your Environment settings page.

Screenshot that shows the environment settings page with the GitHub connector now connected.

The Defender for Cloud service automatically discovers the organizations where you installed the DevOps security GitHub application.

Note

To ensure proper functionality of advanced DevOps posture capabilities in Defender for Cloud, only one instance of a GitHub organization can be onboarded to the Azure Tenant you are creating a connector in.

The DevOps security blade shows your onboarded repositories grouped by Organization. The Recommendations blade shows all security assessments related to GitHub repositories.

Next steps