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

Saiba como usar executores hospedados GitHub em 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 a rede privada do Azure para executores hospedados em 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 para 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 comandos a seguir GitHub CLI para recuperar o databaseId. Substitua SUBDOMAIN pelo subdomínio da sua empresa.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 em 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. Adicionar o GitHubexecutor hospedado ao grupo de executores corporativos

Observação

Ao adicionar o executor hospedado em GitHub a um grupo de executores, selecione o grupo de executores que você criou nas etapas anteriores.

  1. Adicione o executor hospedado em 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 na rede, clique em à direita da configuração de rede. Em seguida, clique em Editar configuração.
  5. Para desabilitar uma configuração de rede, clique em à direita da configuração de rede. Em seguida, clique em Desabilitar.
  6. Para excluir uma configuração de rede, clique em à direita da configuração de rede. Em seguida, clique em Excluir.

5. Opcionalmente, adicione uma rede de failover a uma configuração de rede

Observação

O failover da VNET está em versão prévia pública e está sujeito a alterações.

Você pode configurar uma rede de contingência para sua configuração de rede. Uma rede de failover é uma sub-rede secundária da Rede Virtual do Azure, que pode estar em uma região diferente do Azure da sua sub-rede primária. Se sua sub-rede primária ficar indisponível devido a uma falha regional ou outra interrupção, você poderá habilitar a rede de contingência para rotear o tráfego do runner por meio da sub-rede secundária, mantendo a continuidade para seus GitHub Actions fluxos de trabalho.

Principais pontos sobre o failover da VNET:

  • A sub-rede de failover pode residir em uma região do Azure diferente da sub-rede primária.
  • Alternar entre sub-redes primárias e de failover é um processo manual. Você habilita ou desabilita a rede de failover a seu critério.
  • As sub-redes primárias e de failover devem ser configuradas com os recursos necessários do Azure (VNET/sub-rede, configurações de rede, etc.) antes que você possa usar o failover.
  • A sub-rede de contingência deve estar em uma região com suporte.

Antes de adicionar uma rede de failover, verifique se você configurou os recursos do Azure (VNET, sub-rede, grupo de segurança de rede e recurso de configurações de rede) para a sub-rede secundária, seguindo os mesmos procedimentos "Configurando seus recursos do Azure" acima. A sub-rede de failover pode estar em uma região do Azure diferente da sua sub-rede primária.

  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 no ícone de edição () ao lado da configuração de rede à qual você deseja adicionar uma rede de failover. Em seguida, clique em Editar configuração.
  5. Clique em Adicionar rede de failover.
  6. Na janela pop-up, insira o ID do recurso de configurações de rede para sua sub-rede secundária (failover) do Azure.
  7. Clique em Add Azure Virtual Network.
  8. Agora você verá duas sub-redes listadas na configuração de rede: a primária e o failover, rotuladas adequadamente.

6. Opcionalmente, habilite ou desabilite a rede de failover

Depois de adicionar uma rede de failover, você pode habilitá-la para rotear o tráfego por meio da sub-rede secundária ou desabilitá-la para retornar à sub-rede primária.

  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 no ícone de edição () ao lado da configuração de rede. Em seguida, clique em Editar configuração.
  5. Para alternar para a rede de failover, clique em Ativar VNET de failover. O tráfego do executor será roteado por meio da sub-rede de failover.
  6. Para alternar de volta para a rede primária, clique em Desativar failover VNET. O tráfego do executor retornará para a sub-rede primária.

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.