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

Product: Marketplace Offerings
Source: https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/step2/

Now 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".

::::tabs
:::tab[Organization runners]
![PAT scopes for organization runners](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/step2.png)
:::
:::tab[Organization runners on private repo]
![PAT scopes for organization runners on a private repo](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/step2-1.png)
:::
:::tab[Personal repository runners]
![PAT scopes for personal repository runners](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/2023-09-15_13-50-27.png)
:::
::::

## 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.

```bash
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.

![Scaling the VMSS instance count](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/2023-09-15_13-53-43.png)

:::details[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.

```bash
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.

![Scaling the VMSS instance count](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/2023-09-15_13-53-43.png)
:::

## 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.

```powershell
$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.

![Scaling the VMSS instance count](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/2023-09-15_13-53-43.png)

## Advanced configuration examples for the VMSS

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

If you want 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:

![Termination notifications enabled on the VMSS](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/step2-2.png)

Also the Terraform module has a variable for this:

```hcl
  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.

![The registered runner in GitHub](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/media/2023-09-15_14-12-59.png)

[Continue to step 3 - Testing the self hosted runner](https://docs.fortytwo.io/marketplace-offerings/self-hosted-runners/github/step3/)
