Configurando a rede privada para executores hospedados por GitHub em sua empresa

Saiba como usar executores hospedados pela GitHub com uma rede privada do Azure.

Quem pode usar esse recurso?

Enterprise owners can configure private networking for GitHub-hosted runners at the enterprise level.

Neste artigo

Sobre redes privadas do Azure com executores hospedados por GitHub

Para usar executores hospedados em GitHub com a VNET do Azure, primeiro configure seus recursos do Azure. Em seguida, crie uma configuração da rede privada em GitHub.

Os procedimentos a seguir guiarão você pelas etapas.

Para obter mais informações sobre como solucionar problemas comuns com o uso de executores hospedados em GitHub com o Azure VNET, consulte Solução de problemas nas configurações de rede privada do Azure para runners hospedados no GitHub em sua empresa.

Configurando seus recursos de Azure

Você usará um script para automatizar a configuração dos recursos do Azure.

Pré-requisitos

  • Use uma conta do Azure com a função Colaborador de Assinatura e a função Colaborador de Rede. Essas funções permitem registrar o provedor de recursos GitHub.Network e delegar a sub-rede. Para obter mais informações, consulte Funções internas do Azure no Microsoft Learn.

  • Para associar corretamente as sub-redes ao usuário certo, os recursos de NetworkSettings do Azure devem ser criados nas mesmas assinaturas onde as redes virtuais são criadas.

  • Para garantir a disponibilidade de recursos/residência de dados, os recursos devem ser criados na mesma região do Azure.

  • O tráfego de rede de saída da sub-rede não deve estar sujeito à interceptação TLS, pois nossas Máquinas Virtuais não serão configuradas para confiar em certificados intermediários que sua rede usa para executar a interceptação TLS. Para obter mais detalhes, consulte Certificados usados pelo Firewall do Azure Premium na documentação da Microsoft.

    Se você precisar usar a interceptação TLS, poderá instalar certificados intermediários por meio de uma imagem personalizada. Confira Usando imagens personalizadas.

  • Salve o seguinte arquivo .bicep. Dê o nome actions-nsg-deployment.bicep para o arquivo.

    O arquivo.bicep que fornecemos contém o conjunto mínimo de regras para usar executores hospedados na GitHub com a VNET do Azure. Pode ser necessário adicionar regras para seu caso de uso específico.

    Se você usar a GitHub Enterprise Cloud com residência de dados, na seção AllowOutBoundGitHub, também precisará incluir os intervalos de IP de entrada do GHE.com. Confira Detalhes de rede do GHE.com.

    Observação

    Como alternativa ao uso do arquivo a seguir, para permitir que o GitHub Actions se comunique com os executores, você pode permitir os mesmos domínios de firewall necessários para a comunicação entre os executores auto-hospedados e o GitHub. Para saber mais, confira Referência de executores auto-hospedados. Para determinar o intervalo de endereços IP de sub-rede apropriado, recomendamos adicionar um buffer de 30% à simultaneidade máxima de trabalho prevista. Por exemplo, se os executores da configuração de rede estiverem definidos para uma simultaneidade de trabalho máxima de 300, é recomendável utilizar um intervalo de endereços IP de sub-rede que possa acomodar pelo menos 390 executores. Esse buffer ajuda a garantir que sua rede possa lidar com aumentos inesperados nas necessidades de VM para atender à simultaneidade de trabalho sem ficar sem endereços IP.

    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: 'AllowVnetOutBoundOverwrite'
        properties: {
          protocol: 'TCP'
          sourcePortRange: '*'
          destinationPortRange: '443'
          sourceAddressPrefix: '*'
          destinationAddressPrefix: 'VirtualNetwork'
          access: 'Allow'
          priority: 200
          direction: 'Outbound'
          destinationAddressPrefixes: []
        }
      }
      {
        name: 'AllowOutBoundActions'
        properties: {
          protocol: '*'
          sourcePortRange: '*'
          destinationPortRange: '443'
          sourceAddressPrefix: '*'
          access: 'Allow'
          priority: 210
          direction: 'Outbound'
          destinationAddressPrefixes: [
            '4.175.114.51/32'
            '20.102.35.120/32'
            '4.175.114.43/32'
            '20.72.125.48/32'
            '20.19.5.100/32'
            '20.7.92.46/32'
            '20.232.252.48/32'
            '52.186.44.51/32'
            '20.22.98.201/32'
            '20.246.184.240/32'
            '20.96.133.71/32'
            '20.253.2.203/32'
            '20.102.39.220/32'
            '20.81.127.181/32'
            '52.148.30.208/32'
            '20.14.42.190/32'
            '20.85.159.192/32'
            '52.224.205.173/32'
            '20.118.176.156/32'
            '20.236.207.188/32'
            '20.242.161.191/32'
            '20.166.216.139/32'
            '20.253.126.26/32'
            '52.152.245.137/32'
            '40.118.236.116/32'
            '20.185.75.138/32'
            '20.96.226.211/32'
            '52.167.78.33/32'
            '20.105.13.142/32'
            '20.253.95.3/32'
            '20.221.96.90/32'
            '51.138.235.85/32'
            '52.186.47.208/32'
            '20.7.220.66/32'
            '20.75.4.210/32'
            '20.120.75.171/32'
            '20.98.183.48/32'
            '20.84.200.15/32'
            '20.14.235.135/32'
            '20.10.226.54/32'
            '20.22.166.15/32'
            '20.65.21.88/32'
            '20.102.36.236/32'
            '20.124.56.57/32'
            '20.94.100.174/32'
            '20.102.166.33/32'
            '20.31.193.160/32'
            '20.232.77.7/32'
            '20.102.38.122/32'
            '20.102.39.57/32'
            '20.85.108.33/32'
            '40.88.240.168/32'
            '20.69.187.19/32'
            '20.246.192.124/32'
            '20.4.161.108/32'
            '20.22.22.84/32'
            '20.1.250.47/32'
            '20.237.33.78/32'
            '20.242.179.206/32'
            '40.88.239.133/32'
            '20.121.247.125/32'
            '20.106.107.180/32'
            '20.22.118.40/32'
            '20.15.240.48/32'
            '20.84.218.150/32'
          ]
        }
      }
      {
        name: 'AllowOutBoundGitHub'
        properties: {
          protocol: '*'
          sourcePortRange: '*'
          destinationPortRange: '443'
          sourceAddressPrefix: '*'
          access: 'Allow'
          priority: 220
          direction: 'Outbound'
          destinationAddressPrefixes: [
            '140.82.112.0/20'
            '143.55.64.0/20'
            '185.199.108.0/22'
            '192.30.252.0/22'
            '20.175.192.146/32'
            '20.175.192.147/32'
            '20.175.192.149/32'
            '20.175.192.150/32'
            '20.199.39.227/32'
            '20.199.39.228/32'
            '20.199.39.231/32'
            '20.199.39.232/32'
            '20.200.245.241/32'
            '20.200.245.245/32'
            '20.200.245.246/32'
            '20.200.245.247/32'
            '20.200.245.248/32'
            '20.201.28.144/32'
            '20.201.28.148/32'
            '20.201.28.149/32'
            '20.201.28.151/32'
            '20.201.28.152/32'
            '20.205.243.160/32'
            '20.205.243.164/32'
            '20.205.243.165/32'
            '20.205.243.166/32'
            '20.205.243.168/32'
            '20.207.73.82/32'
            '20.207.73.83/32'
            '20.207.73.85/32'
            '20.207.73.86/32'
            '20.207.73.88/32'
            '20.217.135.1/32'
            '20.233.83.145/32'
            '20.233.83.146/32'
            '20.233.83.147/32'
            '20.233.83.149/32'
            '20.233.83.150/32'
            '20.248.137.48/32'
            '20.248.137.49/32'
            '20.248.137.50/32'
            '20.248.137.52/32'
            '20.248.137.55/32'
            '20.26.156.215/32'
            '20.26.156.216/32'
            '20.26.156.211/32'
            '20.27.177.113/32'
            '20.27.177.114/32'
            '20.27.177.116/32'
            '20.27.177.117/32'
            '20.27.177.118/32'
            '20.29.134.17/32'
            '20.29.134.18/32'
            '20.29.134.19/32'
            '20.29.134.23/32'
            '20.29.134.24/32'
            '20.87.245.0/32'
            '20.87.245.1/32'
            '20.87.245.4/32'
            '20.87.245.6/32'
            '20.87.245.7/32'
            '4.208.26.196/32'
            '4.208.26.197/32'
            '4.208.26.198/32'
            '4.208.26.199/32'
            '4.208.26.200/32'
            '4.225.11.196/32'
            '4.237.22.32/32'
          ]
        }
      }
      {
        name: 'AllowStorageOutbound'
        properties: {
          protocol: '*'
          sourcePortRange: '*'
          destinationPortRange: '443'
          sourceAddressPrefix: '*'
          destinationAddressPrefix: 'Storage'
          access: 'Allow'
          priority: 230
          direction: 'Outbound'
          destinationAddressPrefixes: []
        }
      }
    ]
  }
}

1. Obtenha o databaseId da sua empresa.

Dica

Seu token exigirá, no mínimo, permissões de read:enterprise para executar uma consulta bem-sucedida.

Você pode usar a consulta GraphQL a seguir para recuperar sua empresa databaseId. Você usará o databaseId da empresa para o valor da variável de ambiente DATABASE_ID na próxima etapa. Para saber mais sobre como trabalhar com GraphQL, confira Realizar chamadas com o GraphQL.

Variável da consultaDescrição
slugO campo de dados dinâmico da conta empresarial, que você pode identificar conferindo a URL da sua empresa, https://github.com/enterprises/SLUG ou https://SLUG.ghe.com.
query(
  $slug: String!
){
  enterprise (slug: $slug)
  {
    slug
    databaseId
  }
}
'
Variables
{
  "slug": "ENTERPRISE_SLUG"
}

Exemplo do GitHub.com

Use o comando curl a seguir para encontrar sua 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

Exemplo para GHE.com

Você pode usar os seguintes comandos GitHub CLI para recuperar o databaseId. Substitua SUBDOMAIN pelo subdomínio da sua empresa do GHE.com.

Shell
gh auth login -s 'read:enterprise' -h SUBDOMAIN.ghe.com

gh api graphql --hostname SUBDOMAIN.ghe.com -f query='query($slug: String!) { enterprise (slug: $slug) { slug databaseId } }' -f slug='SUBDOMAIN'

2. Use um script para configurar os recursos do Azure

Use o script a seguir para configurar uma sub-rede para redes privadas do Azure. O script cria todos os recursos no mesmo grupo de recursos.

Para usar o script, preencha os valores das variáveis de ambiente do espaço reservado com os valores reais e execute o script em um shell bash ou no Windows Subsistema do Windows para Linux.

Observação

  • Execute o script a seguir no mesmo diretório em que você salvou o arquivo actions-nsg-deployment.bicep.
  • Ao definir a variável de ambiente YOUR_AZURE_LOCATION, use o nome da sua região. Esse valor é diferente do nome de exibição da sua região. Para ver uma lista de nomes e nomes de exibição, use a az account list-locations -o table.
  • Quando você cria o recurso de configurações de rede, um link de associação de serviço é aplicado à sub-rede fornecida. Esse link evita a exclusão acidental da sub-rede durante seu uso pelo serviço GitHub Actions.
  • Se você personalizar esse script para usar recursos de rede em sub-redes existentes, deverá garantir que todas as interfaces de rede (NICs) existentes conectadas à sub-rede sejam excluídas antes que a sub-rede seja delegada ao serviço GitHub Actions. Caso contrário, o serviço não conseguirá aplicar o link de associação de serviço à sub-rede.
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 Enterprisedatabase 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
export API_VERSION=2024-04-02

# 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\", \"businessId\": \"$DATABASE_ID\" }}" --is-full-object --output table --query "{GitHubId:tags.GitHubId, name:name}" --api-version $API_VERSION

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

O script retornará a carga completa do recurso criado. O valor de hash GitHubId retornado na carga do recurso criado é a ID do recurso de configurações de rede que você usará nas próximas etapas ao definir uma configuração de rede na GitHub.

Criando uma configuração de rede para sua empresa no GitHub

Depois de configurar seus recursos do Azure, use uma VNET (Rede Virtual) do Azure para a rede privada criando uma configuração de rede na empresa ou organização. Em seguida, você pode associar essa configuração de rede a grupos de executores.

Observe que a configuração inicial precisa estar no nível da empresa ao criar as configurações de rede definidas com o Azure. É por isso que, ao obter a databaseId, as etapas exigem que você configure o campo de dados dinâmico da empresa. As organizações só terão permissão para criar configurações de rede próprias depois que a empresa tiver sido estabelecida e habilitada por meio da política da empresa para a rede de computação hospedada. Para obter mais informações sobre os grupos de executores, confira Como controlar o acesso a executores maiores.

Depois que a configuração de rede estiver associada a um grupo de executores, todos os executores desse grupo terão acesso à VNET do Azure que foi conectada à configuração subjacente.

Pré-requisitos

Verifique se seus recursos do Azure foram configurados antes de adicionar uma configuração da rede em GitHub. Para saber mais, confira Configurando a rede privada para executores hospedados por GitHub em sua empresa.

1. Adicione uma nova configuração de rede para sua empresa

  1. Navegue até sua empresa. Por exemplo, na página Enterprises em GitHub.com.
  2. Na parte superior da página, clique em Settings.
  3. Na barra lateral esquerda, clique em Rede de computação hospedada.
  4. Clique na lista suspensa Nova configuração de rede. Em seguida, clique em Azure rede privada.
  5. Dê um nome para a configuração da rede.
  6. Clique em Add Azure Virtual Network.
  7. Na janela pop-up, insira a ID do recurso de configurações de rede que você recuperou quando configurou seus recursos de Azure para rede privada.
  8. Clique em Add Azure Virtual Network.

2. Crie um grupo de runners para sua empresa

Observação

Para que o grupo de executores seja acessível pelos repositórios dentro de suas organizações, esses repositórios devem ter acesso a esse grupo de executores no nível da organização. Para saber mais, confira Como controlar o acesso a executores maiores.

  1. Crie um novo grupo de runners para sua organização. Para saber mais sobre como criar um grupo de runners, confira Como controlar o acesso a executores maiores.
  2. Para escolher uma política para o acesso da organização, selecione o menu suspenso Acesso à organização e clique em uma política. Você pode configurar um grupo de executor para que possa ser acessado por uma lista específica de organizações ou a todas as organizações da empresa.
  3. Ao configurar seu grupo de executores, em "Configurações de rede", use o menu suspenso para selecionar a configuração de rede criada para a VNET do Azure.
  4. Para criar o grupo e aplicar a política, clique em Criar grupo.

3. Adicione um executor hospedado pela GitHub

ao grupo de executores corporativos

Observação

Ao adicionar seu runner hospedado em GitHub a um grupo de runners, selecione o grupo de runners que você criou nos procedimentos anteriores.

  1. Adicione um executor hospedado pela GitHub ao grupo de executores. Para saber mais, confira Gerenciar executores maiores.

4. Opcionalmente, gerencie configurações de rede

  1. Navegue até sua empresa. Por exemplo, na página Enterprises em GitHub.com.
  2. Na parte superior da página, clique em Settings.
  3. Na barra lateral esquerda, clique em Rede de computação hospedada.
  4. Para editar uma configuração de rede, à direita da configuração de rede, clique em . Em seguida, clique em Editar configuração.
  5. Para desabilitar uma configuração de rede, à direita da configuração de rede, clique em . Em seguida, clique em Desabilitar.
  6. Para excluir uma configuração de rede, à direita da configuração de rede, clique em . Em seguida, clique em Excluir.

Habilitar a criação de configurações de rede para organizações

Você pode permitir que os proprietários de organizações em uma empresa criem suas próprias configurações de rede no nível da organização.

  1. Navegue até sua empresa. Por exemplo, na página Enterprises em GitHub.com.
  2. Na parte superior da página, clique em Policies.
  3. Clique em Redes de computação hospedada.
  4. Em "Rede de computação hospedada", clique em Habilitar.
  5. Clique em Salvar.

Como excluir uma sub-rede

Quando você cria o recurso de configurações de rede, um link de associação de serviço é aplicado à sub-rede fornecida. Esse link evita a exclusão acidental da sub-rede durante seu uso pelo serviço GitHub Actions.

Antes da exclusão da sub-rede, o link de associação desse serviço precisa ser removido. O link de associação de serviço é removido com segurança automaticamente depois que o recurso de configurações de rede é excluído.

Para excluir o recurso de configurações de rede, a configuração da rede que o usa precisa ser excluída primeiro.

  1. Navegue até sua empresa. Por exemplo, na página Enterprises em GitHub.com.

  2. Na parte superior da página, clique em Settings.

  3. Na barra lateral esquerda, clique em Rede de computação hospedada.

  4. Abra a configuração de rede que está usando a sub-rede que você deseja excluir.

  5. Revise a lista de grupos de executores usando a configuração de rede.

  6. No canto superior direito, clique no botão "". Em seguida, clique em Excluir configuração.

  7. Para excluir o recurso de configurações de rede e remover o link de associação de serviço, use suas próprias entradas com os seguintes comandos com a CLI do Azure. Para obter mais informações, confira a documentação da CLI (interface de linha de comando) do Azure.

    Bash
    az account set --subscription $SUBSCRIPTION_ID
az resource delete -g $RESOURCE_GROUP_NAME --name $NETWORK_SETTINGS_RESOURCE_NAME --resource-type 'GitHub.Network/networkSettings' --api-version $API_VERSION

  8. Exclua a sub-rede no Azure. Para obter informações, confira Excluir uma sub-rede no Microsoft Learn.