GitHub-Hosted Runners in an Azure VNet: Private Access Guide

In the self-hosted runners post, I described a problem most platform teams eventually hit: the pipeline works until the resources it needs are private. The answer I gave was to put a runner inside your network and operate it yourself.

That needs a qualification. GitHub also supports hosted runners connected to an Azure VNet. You still own the network design, but you don’t necessarily have to own the runner infrastructure.

If you’ve read my Azure DevOps with private endpoints post, the shape will feel familiar. Managed DevOps Pools solve this problem for Azure DevOps. This is the GitHub equivalent, and I should have given it the same airtime.

In this post I’ll explain what actually changes when a GitHub-hosted runner joins your VNet, walk through an example where a runner reads from a storage account with public access disabled, and give you a workflow that proves it works layer by layer. Then I’ll come back to the question that matters: when would I still choose to run my own?

What actually changes with VNet-connected hosted runners?

There are three models worth separating:

Runner model Who operates the runner? Private Azure connectivity
Standard GitHub-hosted GitHub Requires an additional connectivity solution
GitHub-hosted with Azure VNet networking GitHub Through the configured Azure subnet
Self-hosted Your team Through the network where you deploy it

The middle option works through VNet injection. The runner VM still lives in GitHub’s infrastructure, but its network attachment takes an IP address from a subnet you’ve delegated to GitHub. From that point, the runner’s traffic behaves as if it originated in your VNet. It uses your DNS, your routes, your NSGs and your outbound path.

That gives you a clean split of responsibility. GitHub provisions, patches, scales and retires the runner. Your team still designs the network access, DNS resolution, outbound controls and Azure permissions. The hard part of private connectivity was never really the VM, and it doesn’t go away here.

One thing to be clear about early: changing nothing and hoping runs-on: ubuntu-latest will reach your private endpoint won’t work. Azure private networking only applies to larger runners, which you create explicitly, place in a runner group and target by name. The standard runners your workflows use today are not VNet-connected and can’t be.

Check the prerequisites before designing around it

A few requirements can rule this option in or out before you draw a single subnet. These change over time, so treat the current GitHub documentation as the source of truth.

  • Plan. You need GitHub Team or GitHub Enterprise Cloud. Organisation owners can configure it at organisation level, and enterprise owners at enterprise level.
  • Runner types. Ubuntu and Windows larger runners from 2 to 64 vCPU are supported. arm64 and GPU runners are supported in a smaller set of US regions only.
  • Region. The subnet must sit in a supported Azure region. For UK readers, UK South, UK West and North Europe are all on the list today. If your private endpoints live elsewhere, global VNet peering is the documented route.
  • Azure permissions. The account doing the setup needs Subscription Contributor and Network Contributor so it can register the GitHub.Network resource provider and delegate the subnet. The networking resource must be in the same subscription and region as the VNet.
  • Subnet capacity. Every concurrent job consumes an IP address. GitHub recommends sizing for maximum concurrency plus a 30% buffer.
  • Cost. Larger runners never draw from your plan’s included minutes, even in public repositories. Every minute is billed. Add the Azure side too: your outbound path (NAT gateway or firewall), private endpoints and DNS all carry their own charges.

There are also a couple of design constraints worth knowing now rather than later. Outbound traffic from the runner subnet can’t be subject to TLS inspection, and static public IPs aren’t available for VNet-connected larger runners.

The example architecture

To keep this concrete, the example has one goal: a GitHub-hosted runner lists blobs in an Azure Storage account that has public network access disabled and is only reachable through a private endpoint.

Architecture diagram showing a GitHub-hosted larger runner whose network attachment takes an IP from a delegated Azure subnet. The runner resolves the storage account’s normal hostname through Azure-provided DNS and a linked private DNS zone, reaches it over HTTPS through a private endpoint, and reaches GitHub, Entra ID and ARM through an explicit outbound path

There are two independent requirements here, and it’s worth keeping them separate in your head because they fail in different ways:

  • Connectivity. Can the runner resolve the storage account’s name to the private endpoint, and can it reach that address on 443?
  • Authorisation. Does the workflow’s identity have permission to perform the data operation it’s attempting?

You can have perfect connectivity and still be denied, or a valid identity with no route to the data. It’s easy to treat them as one problem, and debugging gets much slower when you do. If DNS and routing in hub and spoke are new territory, Part 1 of the networking series covers them in more depth than I will here.

Connect the runner to the network

Here’s the minimum setup, in the order I’d do it. I’m using the Azure CLI so each step is visible. GitHub also publishes a Terraform module for the Azure side, which is what I’d use for anything beyond a proof of concept.

1. Prepare the subnet

Register the resource provider, then create a subnet delegated to GitHub.Network/networkSettings. I’m creating it as a private subnet with a NAT gateway attached, because the runner still needs to reach GitHub and Entra ID.

az provider register --namespace GitHub.Network

az network vnet subnet create \
  --resource-group rg-gh-runners \
  --vnet-name vnet-gh-runners \
  --name snet-gh-runners \
  --address-prefixes 10.50.1.0/24 \
  --delegations GitHub.Network/networkSettings \
  --network-security-group nsg-gh-runners \
  --nat-gateway natgw-gh-runners \
  --default-outbound false

The outbound path deserves a moment. Azure no longer gives new VNets implicit internet access by default, so a runner subnet without an explicit outbound path simply can’t reach GitHub, and the job will never pick up. A NAT gateway gives you outbound connectivity. Routing through a firewall with a UDR gives you outbound connectivity with traffic filtering. GitHub also recommends explicitly blocking all inbound traffic to the runner subnet in your NSG, since the runner’s address is in your network and GitHub can’t do that for you.

For outbound filtering, GitHub originally published an NSG template built on IP ranges. That approach has been retired. The current guidance is to allow-list the Actions domains published by the GitHub meta API using whatever domain filtering you already run, such as Azure Firewall application rules.

2. Configure DNS and the private endpoint

The runner uses your VNet’s DNS configuration, so the private endpoint’s record has to be resolvable from the runner VNet. The zone holds the records, but the runner queries a resolver. In this example, that’s Azure-provided DNS, which answers from a private DNS zone linked directly to the VNet:

az network private-dns zone create \
  --resource-group rg-gh-runners \
  --name privatelink.blob.core.windows.net

az network private-dns link vnet create \
  --resource-group rg-gh-runners \
  --zone-name privatelink.blob.core.windows.net \
  --name link-vnet-gh-runners \
  --virtual-network vnet-gh-runners \
  --registration-enabled false

The private endpoint for the blob sub-resource then sits in snet-private-endpoints, with a DNS zone group so the A record is created and maintained for you. In a hub and spoke design, the zone is usually linked to the hub, with spokes resolving through a DNS Private Resolver or custom DNS servers. The principle is the same: whatever the runner VNet uses for DNS has to return the private address.

3. Create the network settings resource

This is the resource that joins the Azure side to GitHub. It needs the subnet ID and your organisation’s databaseId, which you can fetch with the GitHub CLI:

gh api graphql \
  -f query='query($login: String!) { organization(login: $login) { login databaseId } }' \
  -f login=YOUR_ORG

Then create the resource:

SUBNET_ID=$(az network vnet subnet show \
  --resource-group rg-gh-runners \
  --vnet-name vnet-gh-runners \
  --name snet-gh-runners \
  --query id -o tsv)

az resource create \
  --resource-group rg-gh-runners \
  --name ns-gh-runners-uksouth \
  --resource-type GitHub.Network/networkSettings \
  --api-version 2024-04-02 \
  --is-full-object \
  --properties "{ \"location\": \"uksouth\", \"properties\": { \"subnetId\": \"$SUBNET_ID\", \"businessId\": \"$DATABASE_ID\" } }" \
  --query "tags.GitHubId" -o tsv

The GitHubId it returns is what you’ll paste into GitHub. Creating this resource also places a service association link on the subnet, which stops anyone deleting it while GitHub is using it. If you need to tear down, remove the configuration in GitHub first, then the network settings resource, then the subnet.

4. Create the network configuration and runner

In your organisation settings, go to Hosted compute networking, choose New network configuration, then Azure private network, and add the GitHubId from the previous step.

Next, create a runner group and select that network configuration for it. Then create a larger runner (in this example, a 2-core Ubuntu runner called ubuntu-vnet-2core) inside that group. Any runner in the group now takes its IP address from your runner subnet.

5. Restrict which repositories can use it

When creating the runner group, set repository access to selected repositories only. This is the step that’s easy to skip in a proof of concept and painful to retrofit later. A runner with a network path to private resources is a privileged asset, and the runner group is the boundary that decides which workflows can sit on that network.

Targeting the runner

Workflows target the runner by group and label:

runs-on:
  group: azure-vnet-uksouth
  labels: ubuntu-vnet-2core

Prove private access works

This is the part I care most about. “The pipeline went green” isn’t evidence that traffic took the private path. A short workflow that checks each layer in turn is.

name: verify-private-storage-access

on:
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

env:
  STORAGE_ACCOUNT: stghrunnersdemo01
  CONTAINER: private-access-test
  EXPECTED_PREFIX: "10.50.2."

jobs:
  verify:
    runs-on:
      group: azure-vnet-uksouth
      labels: ubuntu-vnet-2core
    environment: ci
    steps:
      - name: 1. Resolve the normal service hostname
        run: dig "${STORAGE_ACCOUNT}.blob.core.windows.net" +noall +answer

      - name: 2. Assert it resolved to the private endpoint
        run: |
          IP=$(dig +short "${STORAGE_ACCOUNT}.blob.core.windows.net" | tail -n1)
          echo "Resolved to: $IP"
          if [[ "$IP" != ${EXPECTED_PREFIX}* ]]; then
            echo "::error::Expected an address in ${EXPECTED_PREFIX}x, got $IP"
            exit 1
          fi

      - name: 3. Check HTTPS connectivity
        run: |
          curl -s -o /dev/null --connect-timeout 10 \
            -w "HTTP %{http_code} from %{remote_ip}\n" \
            "https://${STORAGE_ACCOUNT}.blob.core.windows.net/"

      - name: 4. Authenticate to Azure with OIDC
        uses: azure/login@v2
        with:
          client-id: ${{ vars.AZURE_CLIENT_ID }}
          tenant-id: ${{ vars.AZURE_TENANT_ID }}
          subscription-id: ${{ vars.AZURE_SUBSCRIPTION_ID }}

      - name: 5. List blobs in the test container
        run: |
          az storage blob list \
            --account-name "$STORAGE_ACCOUNT" \
            --container-name "$CONTAINER" \
            --auth-mode login \
            --query "[].name" -o tsv

A few notes on why each step is there.

Steps 1 and 2 query the normal hostname, not the privatelink one. That’s what your tools will use, so that’s what needs to resolve privately. From inside the VNet, the answer should be a CNAME to the privatelink name followed by an A record in your private endpoint subnet (TTLs will differ):

stghrunnersdemo01.blob.core.windows.net.             IN CNAME stghrunnersdemo01.privatelink.blob.core.windows.net.
stghrunnersdemo01.privatelink.blob.core.windows.net. IN A     10.50.2.4

Run the same query from your laptop and you’ll see the same CNAME, but it resolves on to a public address instead. That difference is the whole point of the private DNS zone.

Step 3 is deliberately unauthenticated. An anonymous request to the account root will come back with a 4xx, and that’s fine. Any HTTP status code proves that the TLS handshake completed and the request reached the storage service. A status of 000 means no connection was made at all. The value that matters is the remote IP. If it’s 10.50.2.4, the request went through the private endpoint. If it’s a public address, DNS is wrong, whatever the status code says.

Step 4 uses OIDC, so there’s no secret stored in the repository. I’ve covered the federated credential setup in the OIDC guide, so I won’t repeat it here. In this example, the federated credential’s subject is scoped to the ci environment, which matches the environment set on the job.

Step 5 is the only step that proves data access. The identity should have Storage Blob Data Reader assigned at the container scope and nothing else. Upload a single test file to the container before running the workflow, so a successful run prints its name rather than an empty result that’s harder to interpret.

Why a successful login proves less than you’d think

It’s tempting to treat a green azure/login step as proof that everything works. It isn’t. The login exchanges the GitHub token with Entra ID and talks to Azure Resource Manager, and both of those are public endpoints reached through your outbound path, not through the private endpoint. A successful login tells you the federated credential matches. It tells you nothing about whether the runner can reach the storage data plane, or whether the identity holds a data role.

The same applies to control plane roles. An identity with Contributor on the storage account can manage it but, without a data role, can’t list a single blob using --auth-mode login. That’s why step 5 has to exist.

When it fails, identify which layer failed

Because each step tests one layer, a failure points you at the right place:

Symptom Investigate
Job never starts Runner availability, group access and workflow selection
Service resolves to a public address DNS configuration and private zone resolution
Connection times out Routing, NSGs, firewall rules and outbound access
Azure login fails OIDC configuration and federated credential matching
Connection succeeds but the operation is denied Data permissions and service access configuration

Some specifics that make these quicker to diagnose:

  • Job never starts. Check that the repository is allowed to use the runner group, that the group is linked to the network configuration, and that runs-on names the group and label correctly. If those are fine, check outbound. A runner that can’t reach GitHub can’t pick up the job, and from the workflow’s point of view that just looks like waiting.
  • Public address. If step 2 fails with a public IP, the private DNS zone isn’t linked to the VNet the runner is using, or the VNet’s custom DNS servers don’t forward to Azure DNS for the privatelink zone.
  • Login fails. An AADSTS70021 error means no federated credential matched the token’s subject. The usual cause is a credential scoped to a branch while the job runs in an environment, or the other way around.
  • Denied after connecting. Read the error code rather than assuming RBAC. AuthorizationPermissionMismatch means the request reached the service and the identity lacks a data role. AuthorizationFailure usually means the request was blocked by the storage account’s network rules, which suggests it didn’t arrive through the private endpoint at all.

When I’d still choose self-hosted runners

None of this makes self-hosted runners obsolete. It narrows the set of reasons to run them.

I’d still lean towards self-hosted when:

  • The tooling or machine needs are specialist. Larger runners support custom images, which covers a lot of tooling requirements. But if you need hardware access, kernel-level changes or long-lived machine state, you need machines you control.
  • The workload doesn’t fit the supported envelope. Unsupported regions, runner types outside what’s offered for VNet injection, or a requirement for TLS inspection on runner egress all push you back towards your own compute.
  • Isolation requirements go beyond the network. Some regulated environments need to demonstrate control over the compute itself, not just its network path.
  • You already run it well. If your team operates ARC on an existing AKS platform, or runs Container Apps Jobs as runners, and that’s working, swapping it out has a cost too.

On cost, I’d resist the urge to declare a winner. Larger runner minutes, Container Apps Jobs consumption and an AKS cluster with ARC all scale differently. Calculate it against your actual job volume and duration. And include the engineering time spent patching images and keeping the scaler healthy, because that’s the cost that rarely makes it into the spreadsheet.

Choose who operates the compute

Private access is a requirement. Operating runner infrastructure is a separate decision.

For some teams, self-hosted runners remain the right choice. For others, VNet-connected hosted runners remove infrastructure they would otherwise have to patch, scale and support. Either way, the DNS, routing and permissions still need designing.

If you take one thing from this post, make it the verification workflow. Whichever runner model you choose, a job that proves resolution, connectivity, identity and data access separately will save you hours the first time something breaks.

Your subscription could not be saved. Please try again.
Your subscription to deniscooper.co.uk has been successful.

Join Cloud Engineers Who Build Smarter on Azure

Free checklists, practical guides and the latest posts — built for cloud engineers working with Azure and Terraform.

Leave a Comment