Skip to main content

Configuring private networking for GitHub-hosted runners

Learn how to use GitHub-hosted runners with an Azure private network.

Notes:

  • Using GitHub-hosted runners with an Azure VNET is in beta and subject to change.
  • Only 4-64 CPU Ubuntu and Windows runners are supported with Azure VNET. For more information on these runner types, see "关于较大的运行器."
  • Supported regions include East US, East US 2, and West US 2. To request support for a region that is not in this list, fill out the region request form.

About configuring private networking for GitHub-hosted runners

To use GitHub-hosted runners with Azure VNET, you will need to configure your Azure resources then create an Azure private network configuration in GitHub.

The following procedures will lead you through the entire configuration process.

Warning: Ensure your Azure resources have been configured before adding a network configuration in GitHub. For more information, see "Configuring private networking for GitHub-hosted runners."

Configuring your Azure resources

You will use a script to automate configuring your Azure resources.

Prerequisites

  • Use an Azure account with the Subscription Contributor role and the Network Contributor role. These roles enable you to register the GitHub.Network resource provider and delegate the subnet. For more information, see Azure built-in roles in the Azure documentation.

  • To correctly associate the subnets with the right user, Azure NetworkSettings resources must be created in the same subscriptions where virtual networks are created.

  • To ensure resource availability/data residency, resources must be created in the same Azure region.

  • Save the following .bicep file. Name the file actions-nsg-deployment.bicep.

    Note: Alternatively, to allow GitHub Actions to communicate with the runners, you can allow the same firewall domains that are required for communication between self-hosted runners and GitHub Enterprise Cloud. For more information, see "关于自托管运行程序."

    Bicep
    @description('NSG for outbound rules')
    param location string
    param nsgName string = 'actions_NSG'
    
    resource actions_NSG 'Microsoft.Network/networkSecurityGroups@2017-06-01' = {
      name: nsgName
      location: location
      properties: {
        securityRules: [
          {
            name: 'DenyInternetOutBoundOverwrite'
            properties: {
              protocol: '*'
              sourcePortRange: '*'
              destinationPortRange: '*'
              sourceAddressPrefix: '*'
              destinationAddressPrefix: 'Internet'
              access: 'Deny'
              priority: 400
              direction: 'Outbound'
            }
          }
          {
            name: 'AllowVnetOutBoundOverwrite'
            properties: {
              protocol: 'TCP'
              sourcePortRange: '*'
              destinationPortRange: '443'
              sourceAddressPrefix: '*'
              destinationAddressPrefix: 'VirtualNetwork'
              access: 'Allow'
              priority: 200
              direction: 'Outbound'
              destinationAddressPrefixes: []
            }
          }
          {
            name: 'AllowAzureCloudOutBound'
            properties: {
              protocol: 'TCP'
              sourcePortRange: '*'
              destinationPortRange: '443'
              sourceAddressPrefix: '*'
              destinationAddressPrefix: 'AzureCloud'
              access: 'Allow'
              priority: 210
              direction: 'Outbound'
              destinationAddressPrefixes: []
            }
          }
          {
            name: 'AllowInternetOutBoundGitHub'
            properties: {
              protocol: 'TCP'
              sourcePortRange: '*'
              destinationPortRange: '443'
              sourceAddressPrefix: '*'
              access: 'Allow'
              priority: 220
              direction: 'Outbound'
              destinationAddressPrefixes: [
                '140.82.112.0/20'
                '142.250.0.0/15'
                '143.55.64.0/20'
                '192.30.252.0/22'
                '185.199.108.0/22'
              ]
            }
          }
          {
            name: 'AllowInternetOutBoundMicrosoft'
            properties: {
              protocol: 'TCP'
              sourcePortRange: '*'
              destinationPortRange: '443'
              sourceAddressPrefix: '*'
              access: 'Allow'
              priority: 230
              direction: 'Outbound'
              destinationAddressPrefixes: [
                '13.64.0.0/11'
                '13.96.0.0/13'
                '13.104.0.0/14'
                '20.33.0.0/16'
                '20.34.0.0/15'
                '20.36.0.0/14'
                '20.40.0.0/13'
                '20.48.0.0/12'
                '20.64.0.0/10'
                '20.128.0.0/16'
                '52.224.0.0/11'
                '204.79.197.200'
              ]
            }
          }
        {
            name: 'AllowInternetOutBoundCannonical'
            properties: {
              protocol: 'TCP'
              sourcePortRange: '*'
              destinationPortRange: '443'
              sourceAddressPrefix: '*'
              destinationAddressPrefix: '185.125.188.0/22'
              access: 'Allow'
              priority: 240
              direction: 'Outbound'
              destinationAddressPrefixes: []
            }
          }
        ]
      }
    }
    

1. Obtain the databaseId for your enterprise

You can use the following GraphQL query to retrieve your enterprise databaseId. You will use the enterprise databaseId for the value of the DATABASE_ID environment variable in the next step. For more information on working with GraphQL, see "使用 GraphQL 建立调用."

查询变量说明
slug企业帐户的 slug,可以通过查看企业的 URL (https://github.com/enterprises/SLUG) 来识别。
query(
  $slug: String!
){
  enterprise (slug: $slug)
  {
    slug
    databaseId
  }
}
'
Variables
{
  "slug": "ENTERPRISE_SLUG"
}

Alternatively, you can use the following curl command to find your databaseId.

Shell
curl -H "Authorization: Bearer BEARER_TOKEN" -X POST \
  -d '{ "query": "query($slug: String!) { enterprise (slug: $slug) { slug databaseId } }" ,
        "variables": {
          "slug": "ENTERPRISE_SLUG"
        }
      }' \
https://api.github.com/graphql

2. Use a script to configure your Azure resources

Use the following script to set up a subnet for Azure private networking. The script creates all resources in the same resource group.

To use the script, fill in the placeholder environment variable values with the actual values and run the script from a bash shell or Windows Subsystem for Linux.

Notes:

  • Run the following script in the same directory where you saved the actions-nsg-deployment.bicep file.
  • When setting the YOUR_AZURE_LOCATION environment variable, use your region’s name. This value is different than your region’s display name. To see a list of names and display names, use az account list-locations -o table.
Bash
#!/bin/bash

# This script creates the following resources in the specified subscription:
# - Resource group
# - Network Security Group rules
# - Virtual network (vnet) and subnet
# - Network Settings with specified subnet and GitHub Enterprise databse ID
#
# It also registers the `GitHub.Network` resource provider with the subscription,
# delegates the created subnet to the Actions service via the `GitHub.Network/NetworkSettings`
# resource type, and applies the NSG rules to the created subnet.

# stop on failure
set -e

#set environment
export AZURE_LOCATION=YOUR_AZURE_LOCATION
export SUBSCRIPTION_ID=YOUR_SUBSCRIPTION_ID
export RESOURCE_GROUP_NAME=YOUR_RESOURCE_GROUP_NAME
export VNET_NAME=YOUR_VNET_NAME
export SUBNET_NAME=YOUR_SUBNET_NAME
export NSG_NAME=YOUR_NSG_NAME
export NETWORK_SETTINGS_RESOURCE_NAME=YOUR_NETWORK_SETTINGS_RESOURCE_NAME
export DATABASE_ID=YOUR_DATABASE_ID

# These are the default values. You can adjust your address and subnet prefixes.
export ADDRESS_PREFIX=10.0.0.0/16
export SUBNET_PREFIX=10.0.0.0/24

echo
echo login to Azure
. az login --output none

echo
echo set account context $SUBSCRIPTION_ID
. az account set --subscription $SUBSCRIPTION_ID

echo
echo Register resource provider GitHub.Network
. az provider register --namespace GitHub.Network

echo
echo Create resource group $RESOURCE_GROUP_NAME at $AZURE_LOCATION
. az group create --name $RESOURCE_GROUP_NAME --location $AZURE_LOCATION

echo
echo Create NSG rules deployed with 'actions-nsg-deployment.bicep' file
. az deployment group create --resource-group $RESOURCE_GROUP_NAME --template-file ./actions-nsg-deployment.bicep --parameters location=$AZURE_LOCATION nsgName=$NSG_NAME

echo
echo Create vnet $VNET_NAME and subnet $SUBNET_NAME
. az network vnet create --resource-group $RESOURCE_GROUP_NAME --name $VNET_NAME --address-prefix $ADDRESS_PREFIX --subnet-name $SUBNET_NAME --subnet-prefixes $SUBNET_PREFIX

echo
echo Delegate subnet to GitHub.Network/networkSettings and apply NSG rules
. az network vnet subnet update --resource-group $RESOURCE_GROUP_NAME --name $SUBNET_NAME --vnet-name $VNET_NAME --delegations GitHub.Network/networkSettings --network-security-group $NSG_NAME

echo
echo Create network settings resource $NETWORK_SETTINGS_RESOURCE_NAME
. az resource create --resource-group $RESOURCE_GROUP_NAME  --name $NETWORK_SETTINGS_RESOURCE_NAME --resource-type GitHub.Network/networkSettings --properties "{ \"location\": \"$AZURE_LOCATION\", \"properties\" : {  \"subnetId\": \"/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP_NAME/providers/Microsoft.Network/virtualNetworks/$VNET_NAME/subnets/$SUBNET_NAME\", \"organizationId\": \"$DATABASE_ID\" }}" --is-full-object --output table --query "{GitHubId:tags.GitHubId, name:name}" --api-version 2023-11-01-preview

echo
echo To clean up and delete resources run the following command:
echo az group delete --resource-group $RESOURCE_GROUP_NAME

The script will return the full payload for the created resource. The GitHubId hash value returned in the payload for the created resource is the network settings resource ID you will use in the next steps while configuring a network configuration in GitHub.

Configuring a network configuration in GitHub

After configuring your Azure resources, you can use an Azure Virtual Network (VNET) for private networking by creating a network configuration for your enterprise. Then, you can associate that network configuration to runner groups. For more information about runner groups, see "控制对较大运行器的访问."

Once the network configuration is associated with a runner group, all runners in that group will have access to the Azure VNET that has been connected to the underlying configuration.

Prerequisites

Ensure your Azure resources have been configured before adding a network configuration in GitHub. For more information, see "Configuring private networking for GitHub-hosted runners."

1. Add a new network configuration

  1. 在 GitHub.com 的右上角,单击你的个人资料照片,然后单击“你的企业”。

  2. 在企业列表中,单击您想要查看的企业。

  3. 在企业帐户边栏中,单击“设置”。

  4. In the left sidebar, click Hosted compute networking.

  5. Click the New network configuration dropdown. Then click Azure private network.

  6. Name your network configuration.

  7. Click Add Azure Virtual Network.

  8. In the popup window, enter the network settings resource ID you retrieved when you configured your Azure resources for private networking.

  9. Click Add Azure Virtual Network.

2. Create a runner group

Note: For the runner group to be accessible by repositories within your enterprise-owned organizations, those repositories must have access to that runner group at the organization level. For more information, see "控制对较大运行器的访问."

  1. Create a new runner group for your enterprise. For more information about how to create a runner group, see "控制对较大运行器的访问."
  2. 要选择组织访问策略,请选择“组织访问”下拉列表,然后单击一个策略。 您可以将运行器组配置为可供特定组织列表或企业中的所有组织访问。
  3. While configuring your runner group, under "Network configurations," use the dropdown menu to select the network configuration you created for the Azure VNET.
  4. To create the group and apply the policy, click Create group.

3. Add the GitHub-hosted runner to the runner group

Note: When adding your GitHub-hosted runner to a runner group, select the runner group you created in the previous procedures.

  1. Add the GitHub-hosted runner to the runner group. For more information, see "管理较大的运行器."

4. Optionally, manage network configurations

  1. 在 GitHub.com 的右上角,单击你的个人资料照片,然后单击“你的企业”。

  2. 在企业列表中,单击您想要查看的企业。

  3. 在企业帐户边栏中,单击“设置”。

  4. In the left sidebar, click Hosted compute networking.

  5. To edit a network configuration, to the right of the network configuration, click . Then click Edit configuration.

  6. To disable a network configuration, to the right of the network configuration, click . Then click Disable.

  7. To disable a network configuration, to the right of the network configuration, click . Then click Delete.