Step 2 - Configuring the virtual machine scale set for auto registration¶

Now the the VMSS is up and running, we are ready to configure the Github runner.

Get a PAT from Github for either repo or organization¶

If you are registering the runners for a private repo, the PAT needs to have access to "repo". If you are registering the runners for an organization, the PAT needs to have access to "admin:org". To register a PAT, go to "Settings" -> "Developer settings" -> "Personal access tokens" -> "Tokens (classic) and click "Generate new token".

Organization runners¶

Alt text

Organization runners on private repo¶

Alt text

Personal repository runners¶

For Ubuntu Self-hosted Runners¶

To configure the VMSS to auto-register, use the below new method. The legacy way is just mentioned for reference.

Configure the VMSS to auto register (New)¶

Run the following with az-cli to configure an extension on the VMSS that will auto register the runner with Github. Replace the variables with your correct information.

VMSS=vmss-test-noeast   # Name of the VMSS.
RG=rg-test-noeast       # Resource group for the VMSS.
PAT=ghp_xxx             # The PAT generated in the previous steps.
SCOPE=amesfortytwo      # -s: Can be spesified as either the organization, the owner/repository, or enterprises/enterprisename.
USER=runner             # -u: Username for the runner created on the VMSS.
LABEL=label1,label2     # (Optional) -l: Comma separated list of labels for the runner.
RGROUP=test             # (Optional) -r: Runner Group.
az vmss extension set --vmss-name $VMSS --name customScript --resource-group $RG \
    --version 2.1 --publisher Microsoft.Azure.Extensions \
    --protected-settings "{\"fileUris\": [\"https://raw.githubusercontent.com/fortytwoservices/terraform-azurerm-selfhostedrunnervmss/main/scripts/script.sh\"],\"commandToExecute\": \"RUNNER_CFG_PAT=$PAT bash script.sh -s $SCOPE -u $USER -l $LABEL -r $RGROUP -f\"}"

Scale up the VMSS to at least 1 instance. This can be done in the Azure Portal or with az-cli. Currently you would need to manually scale the number of instances of the VMSS to the number you want.

Configure the VMSS to auto register (Legacy way)¶

Run the following with az-cli to configure an extension on the VMSS that will auto register the runner with Github. Replace the variables with your correct information.

VMSS=vmss-test-noeast   # Name of the VMSS.
RG=rg-test-noeast       # Resource group for the VMSS.
PAT=ghp_xxx             # The PAT generated in the previous steps.
SCOPE=amesfortytwo      # Can be spesified as either the organization or the owner/repository.
USER=runner             # Username for the runner created on the VMSS.
LABEL=label1,label2     # Comma separated list of labels for the runner.
RGROUP=test             # Runner Group. Optional and can be left out/blank.
az vmss extension set --vmss-name $VMSS --name customScript --resource-group $RG \
    --version 2.1 --publisher Microsoft.Azure.Extensions \
    --protected-settings "{\"fileUris\": [\"https://raw.githubusercontent.com/fortytwoservices/terraform-azurerm-selfhostedrunnervmss/main/scripts/script.sh\"],\"commandToExecute\": \"bash script.sh $SCOPE $PAT $USER $LABEL $RGROUP\"}"

Scale up the VMSS to at least 1 instance. This can be done in the Azure Portal or with az-cli. Currently you would need to manually scale the number of instances of the VMSS to the number you want.

For Windows Self-hosted Runners¶

To configure the VMSS to auto-register, use the below new method.

Configure the VMSS to auto register for Windows¶

Run the following with az-cli under a powershell terminal to configure an extension on the VMSS that will auto register the runner with Github. Replace the variables with your correct information.

$VMSS=vmss-test-noeast    # Name of the VMSS.
$RG=rg-test-noeast        # Resource group for the VMSS.
$PAT=ghp_xxx              # The PAT generated in the previous steps.
$GHHOST=github.com        # The domain of the Github instance (default is github.com), use if running GHES.
$SCOPE=amesfortytwo       # Can be spesified as either the organization, the owner/repository, or enterprises/enterprisename.
$USER=runner              # Username for the runner created on the VMSS.
$USERPASSWORD=12Passw0rd_ # Password for the runner user created on the VMSS.
$LABEL=label1,label2      # (Optional) Comma separated list of labels for the runner.
az vmss extension set --vmss-name $VMSS --name customScript --resource-group $RG \
    --version 2.1 --publisher Microsoft.Azure.Extensions \
    --protected-settings "{\"fileUris\": [\"https://raw.githubusercontent.com/fortytwoservices/terraform-azurerm-selfhostedrunnervmss/main/scripts/invoke-ghrunner.ps1\"],\"commandToExecute\": \"powershell -ExecutionPolicy Unrestricted -Command .\\invoke-ghrunner.ps1 -runnerscope $SCOPE -githubpat $PAT -githubhostname $GHHOST -user $USER -userpassword $USERPASSWORD -label $LABEL\"}"

Scale up the VMSS to at least 1 instance. This can be done in the Azure Portal or with az-cli. Currently you would need to manually scale the number of instances of the VMSS to the number you want.

Advanced configuration examples for the VMSS¶

Offboard Github runner upon termination events/scale-down (Linux)¶

If you the Github runner instance to offboard itself from Github upon termination events/scale-down, you will need to enable termination notifications on the VMSS. This can be done with the following in the portal:

Alt text

Also the Terraform module has a variable for this:

  enable_termination_notifications = true

Verify that the runner is registered¶

After the previous has been done, you should be able to verify within the organization or the repository that the runner is registered.

Continue to step 3 - Testing the self hosted runner