## File: README.md # GitHub Actions Runner Images **Table of Contents** - [About](#about) - [Available Images](#available-images) - [Announcements](#announcements) - [Image Definitions](#image-definitions) - [Image Releases](#image-releases) - [Software and Image Support](#software-and-image-support) - [How to Interact with the Repo](#how-to-interact-with-the-repo) - [FAQs](#faqs) ## About This repository contains the source code used to create the VM images for [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) used for Actions, as well as for [Microsoft-hosted agents](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=azure-devops#use-a-microsoft-hosted-agent) used for Azure Pipelines. To build a VM machine from this repo's source, see the [instructions](docs/create-image-and-azure-resources.md). ## Available Images | Image | Architecture | YAML Label | Included Software | | --------------------|--------------|---------------------|------------------| | Ubuntu 26.04 | x64 | `ubuntu-26.04` | [ubuntu-26.04] | | Ubuntu 26.04 Arm64 | arm64 | `ubuntu-26.04-arm` | [ubuntu-26.04-arm64] | | Ubuntu 24.04 | x64 | `ubuntu-latest` or `ubuntu-24.04` | [ubuntu-24.04] | | Ubuntu 24.04 Arm64 | arm64 | `ubuntu-24.04-arm` | [ubuntu-24.04-arm64] | | Ubuntu 22.04 | x64 | `ubuntu-22.04` | [ubuntu-22.04] | | Ubuntu 22.04 Arm64 | arm64 | `ubuntu-22.04-arm` | [ubuntu-22.04-arm64] | | Ubuntu Slim | x64 | `ubuntu-slim` | [ubuntu-slim] | | Xcode 27 [](https://github.com/actions/runner-images/issues/14404) | arm64 | `xcode-27` or `xcode-27-xlarge` | [xcode-27] | | macOS 26 | x64 | `macos-latest-large`, `macos-26-intel`, `macos-26-large` | [macOS-26] | | macOS 26 Arm64 | arm64 | `macos-latest`, `macos-26` or `macos-26-xlarge` | [macOS-26-arm64] | | macOS 15 | x64 | `macos-15-large`, or `macos-15-intel` | [macOS-15] | | macOS 15 Arm64 | arm64 | `macos-15`, or `macos-15-xlarge` | [macOS-15-arm64] | | macOS 14 [](https://github.com/actions/runner-images/issues/13518) | x64 | `macos-14-large` | [macOS-14] | | macOS 14 Arm64 [](https://github.com/actions/runner-images/issues/13518) | arm64 | `macos-14` or `macos-14-xlarge` | [macOS-14-arm64] | | Windows Server 2025 | x64 | `windows-latest`, `windows-2025`, or `windows-2025-vs2026` | [windows-2025-vs2026] | | Windows Server 2022 | x64 | `windows-2022` | [windows-2022] | | Windows 11 Arm64 | arm64 | `windows-11-arm` | [windows-11-arm64] | | Windows 11 Arm64 with Visual Studio 2026 | arm64 | `windows-11-vs2026-arm` | [windows-11-vs2026-arm64] | ### Label scheme - In general the `-latest` label is used for the latest OS image version that is GA. - Before moving the `-latest` label to a new OS version we will announce the change and give sufficient lead time for users to update their workflows. - The `-xlarge` and `-large` suffixes are unique to macOS images and are only available for GitHub Actions. Learn more about [GitHub Actions larger runners](https://docs.github.com/en/actions/reference/runners/larger-runners#available-macos-larger-runners-and-labels). [ubuntu-26.04]: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Readme.md [ubuntu-26.04-arm64]: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Arm64-Readme.md [ubuntu-24.04]: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md [ubuntu-24.04-arm64]: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Arm64-Readme.md [ubuntu-22.04]: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md [ubuntu-22.04-arm64]: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Arm64-Readme.md [ubuntu-slim]: https://github.com/actions/runner-images/blob/main/images/ubuntu-slim/ubuntu-slim-Readme.md [windows-2025-vs2026]: https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-VS2026-Readme.md [windows-2022]: https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md [windows-11-arm64]: https://github.com/actions/runner-images/blob/main/images/windows/Windows11-Arm64-Readme.md [windows-11-vs2026-arm64]: https://github.com/actions/runner-images/blob/main/images/windows/Windows11-VS2026-Arm64-Readme.md [macOS-14]: https://github.com/actions/runner-images/blob/main/images/macos/macos-14-Readme.md [macOS-14-arm64]: https://github.com/actions/runner-images/blob/main/images/macos/macos-14-arm64-Readme.md [macOS-15]: https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md [macOS-15-arm64]: https://github.com/actions/runner-images/blob/main/images/macos/macos-15-arm64-Readme.md [macOS-26]: https://github.com/actions/runner-images/blob/main/images/macos/macos-26-Readme.md [macOS-26-arm64]: https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md [xcode-27]: https://github.com/actions/runner-images/blob/main/images/macos/xcode-27-arm64-Readme.md [self-hosted runners]: https://help.github.com/en/actions/hosting-your-own-runners ## Announcements See notable upcoming changes by viewing issues with the [Announcement](https://github.com/actions/runner-images/labels/Announcement) label. ## Image Definitions ### Beta The purpose of a Beta is to collect feedback on an image before it is released to GA. The goal of a Beta is to identify and fix any potential issues that exist on that image. Images are updated on a weekly cadence. Any workflows that run on a beta image do not fall under the customer [SLA](https://github.com/customer-terms/github-online-services-sla) in place for Actions. Customers choosing to use Beta images are encouraged to provide feedback in the runner-images repo by creating an issue. A Beta may take on different availability, i.e. public vs private. ### GA A GA (General Availability) image has been through a Beta period and is deemed ready for general use. Images are updated on a weekly cadence. In order to be moved to GA the image must meet the following criteria: 1. Has been through a Beta period (public or private) 2. Most major software we install on the image has a compatible version for the underlying OS and 3. All major bugs reported during the Beta period have been addressed. This image type falls under the customer [SLA](https://github.com/customer-terms/github-online-services-sla) for actions. GA images are eventually deprecated according to our guidelines as we only support the latest 2 versions of an OS. #### Latest Migration Process GitHub Actions and Azure DevOps use the `-latest` YAML label (ex: `ubuntu-latest`, `windows-latest`, and `macos-latest`). These labels point towards the newest stable OS version available. The `-latest` migration process is gradual and happens over 1-2 months in order to allow customers to adapt their workflows to the newest OS version. During this process, any workflow using the `-latest` label, may see changes in the OS version in their workflows or pipelines. To avoid unwanted migration, users can specify a specific OS version in the yaml file (ex: macos-14, windows-2022, ubuntu-22.04). ## Image Releases *How to best follow along with changes* 1. Find the latest releases for this repository [here](https://github.com/actions/runner-images/releases). 2. Subscribe to the releases coming out of this repository, instructions [here](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository). 3. Upcoming changes: A pre-release is created when the deployment of an image has started. As soon as the deployment is finished, the pre-release is converted to a release. If you have subscribed to releases, you will get notified of pre-releases as well. - You can also track upcoming changes using the [awaiting-deployment](https://github.com/actions/runner-images/labels/awaiting-deployment) label. 4. For high impact changes, we will post these in advance to the GitHub Changelog on our [blog](https://github.blog/changelog/) and on [X](https://x.com/GHchangelog). - Ex: breaking changes, GA or deprecation of images *Cadence* - We typically deploy weekly updates to the software on the runner images. ## Software and Image Support ### Support Policy - Tools and versions will typically be removed 6 months after they are deprecated or have reached end-of-life - We support (at maximum) 2 GA images and 1 beta image at a time. We begin the deprecation process of the oldest image label once the newest OS image label has been released to GA. - The images generally contain the latest versions of packages installed except for Ubuntu LTS where we mostly rely on the Canonical-provided repositories. - Popular tools can have several versions installed side-by-side with the following strategy: | Tool name | Installation strategy | |-----------|-----------------------| | Docker images | not more than 3 latest LTS OS\tool versions. New images or new versions of current images are added using the standard tool request process | | Java | all LTS versions | | Node.js | 3 latest LTS versions | | Go | 3 latest minor versions | | Python Ruby | 5 most popular `major.minor` versions | | PyPy | 3 most popular `major.minor` versions | | .NET Core | 2 latest LTS versions and 1 latest version. For each feature version only latest patch is installed. Note for [Ubuntu images see details.](./docs/dotnet-ubuntu.md) | | GCC GNU Fortran Clang GNU C++ | 3 latest major versions | | Android NDK | 1 latest non-LTS, 2 latest LTS versions | | Xcode | - only one major version of Xcode will be supported per macOS version - all minor versions of the supported major version will be available - beta and RC versions will be provided "as-is" in the latest available macOS image only no matter of beta/GA status of the image - when a new patch version is released, the previous patch version will be replaced | | Xcode Platforms | - only three major.minor versions of platform tools and simulator runtimes will be available for installed Xcode, including beta/RC versions | ### Package managers usage We use third-party package managers to install software during the image generation process. The table below lists the package managers and the software installed. > [!NOTE] > Third-party repositories are re-evaluated every year to identify if they are still useful and secure. | Operating system | Package manager | Third-party repos and packages | | :--- | :---: | ---: | | Ubuntu | [APT](https://wiki.debian.org/Apt) | [docker](https://download.docker.com/linux/ubuntu) [Eclipse-Temurin (Adoptium)](https://packages.adoptium.net/artifactory/deb/) [Erlang](https://packages.erlang-solutions.com/ubuntu) [Firefox](https://ppa.launchpad.net/mozillateam/ppa/ubuntu) [git-lfs](https://packagecloud.io/install/repositories/github/git-lfs) [git](https://launchpad.net/~git-core/+archive/ubuntu/ppa) [Google Cloud CLI](https://packages.cloud.google.com/apt) [Heroku](https://cli-assets.heroku.com/channels/stable/apt) [HHvm](https://dl.hhvm.com/ubuntu) [MongoDB](https://repo.mongodb.org/apt/ubuntu) [Mono](https://download.mono-project.com/repo/ubuntu) [MS Edge](https://packages.microsoft.com/repos/edge) [PostgreSQL](https://apt.postgresql.org/pub/repos/apt/) [R](https://cloud.r-project.org/bin/linux/ubuntu) | | | [pipx](https://pypa.github.io/pipx) | ansible-core yamllint | | Windows | [Chocolatey](https://chocolatey.org) | No third-party repos installed | | macOS | [Homebrew](https://brew.sh) | [aws-cli v2](https://github.com/aws/homebrew-tap) [azure/bicep](https://github.com/Azure/homebrew-bicep) [mongodb/brew](https://github.com/mongodb/homebrew-brew) | | | [pipx](https://pypa.github.io/pipx/) | yamllint | ### Image Deprecation Policy - Images begin the deprecation process of the oldest image label once a new GA OS version has been released. - Deprecation process begins with an announcement that sets a date for deprecation. - As it gets closer to the date, GitHub begins doing scheduled brownouts of the image. - During this time there will be an Announcement pinned in the repo to remind users of the deprecation. - Finally, GitHub will deprecate the image and it will no longer be available. ### Preinstallation Policy In general, these are the guidelines we follow when deciding what to pre-install on our images: - Popularity: widely-used tools and ecosystems will be given priority. - Latest Technology: recent versions of tools will be given priority. - Deprecation: end-of-life tools and versions will not be added. - Licensing: MIT, Apache, or GNU licenses are allowed. - Time & Space on the Image: we will evaluate how much time is saved and how much space is used by having the tool pre-installed. - Support: If a tool requires the support of more than one version, we will consider the cost of this maintenance. ### Default Version Update Policy - In general, once a new version is installed on the image, we announce the default version update 2 weeks prior to deploying it. - For potentially dangerous updates, we may extend the timeline up to 1 month between the announcement and deployment. ## How to Interact with the Repo - **Issues**: To file a bug report, or request tools to be added/updated, please [open an issue using the appropriate template](https://github.com/actions/runner-images/issues/new/choose) - **Discussions**: If you want to share your thoughts about image configuration, installed software, or bring a new idea, please create a [new discussion](https://github.com/orgs/community/discussions/new?category=actions). Before making a new discussion, please make sure no similar topics were created earlier in the [actions category](https://github.com/orgs/community/discussions/categories/actions). - For general questions about using the runner images or writing your Actions workflow, please open requests in the [GitHub Community discussion Actions category](https://github.com/orgs/community/discussions/categories/actions). ## FAQs ***What images are available for GitHub Actions and Azure DevOps?*** The availability of images for GitHub Actions and Azure DevOps is the same. However, deprecation policies may differ. See documentation for more details: - [GitHub Actions](https://docs.github.com/en/free-pro-team@latest/actions/reference/specifications-for-github-hosted-runners#supported-runners-and-hardware-resources) - [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=azure-devops&tabs=yaml#software) ***What image version is used in my build?*** Usually, image deployment takes 2-3 days, and documentation in the `main` branch is only updated when deployment is finished. To find out which image version and what software versions are used in a specific build, see `Set up job` (GitHub Actions) or `Initialize job` (Azure DevOps) step log. ***Looking for other Linux distributions?*** We do not plan to offer other Linux distributions. We recommend using Docker if you'd like to build using other distributions with the hosted runner images. Alternatively, you can leverage [self-hosted runners] and fully customize your VM image to your needs. ***How do I contribute to the macOS source?*** macOS source lives in this repository and is available for everyone. However, macOS image-generation CI doesn't support external contributions yet so we are not able to accept pull-requests for now. We are in the process of preparing macOS CI to accept contributions. Until then, we appreciate your patience and ask you to continue to make tool requests by filing issues. ***How does GitHub determine what tools are installed on the images?*** For some tools, we always install the latest at the time of the deployment; for others, we pin the tool to specific version(s). For more details please see the [Preinstallation Policy](#preinstallation-policy) ***How do I request that a new tool be pre-installed on the image?*** Please create an issue and get an approval from us to add this tool to the image before creating the pull request. ***What branch should I use to build custom image?*** We strongly encourage customers to build their own images using the main branch. This repository contains multiple branches and releases that serve as document milestones to reflect what software is installed in the images at certain point of time. Current builds are not idempotent and if one tries to build a runner image using the specific tag it is not guaranteed that the build will succeed. --- ## File: docs/create-image-and-azure-resources.md # GitHub Actions Runner Images The runner-images project uses [Packer](https://www.packer.io/) to generate disk images for Windows 2022/2025 and Ubuntu 22.04/24.04/26.04. Each image is configured by a HCL2 Packer template that specifies where to build the image (Azure, in this case), and what steps to run to install software and prepare the disk. The Packer process initializes a connection to the Azure subscription using Azure CLI and creates temporary resources required for the build process: a resource group, network interfaces and a virtual machine from the "clean" image specified in the template. If the VM deployment succeeds, Packer connects to it using SSH or WinRM and begins executing installation steps from the template one-by-one. If any step fails, image generation is aborted, and the temporary VM is terminated. Packer also attempts to clean up all the temporary resources it created (unless otherwise configured). After successful completion of all installation steps, Packer creates a managed image from the temporary VM's disk and deletes the VM. - [Build Agent Preparation](#build-agent-preparation) - [Manual image generation](#manual-image-generation) - [Manual Image Generation Customization](#manual-image-generation-customization) - [Network Security](#network-security) - [Azure Subscription Authentication](#azure-subscription-authentication) - [Generated Machine Deployment](#generated-machine-deployment) - [Automated image generation](#automated-image-generation) - [Required variables](#required-variables) - [Optional variables](#optional-variables) - [Builder variables](#builder-variables) - [Toolset](#toolset) - [Post-generation scripts](#post-generation-scripts) - [Running scripts](#running-scripts) - [Script Details: Ubuntu](#script-details-ubuntu) - [Script Details: Windows](#script-details-windows) ## Build Agent Preparation The build agent is a machine where the Packer process will be started. You can use any physical or virtual machine running Windows or Linux OS. Of course, you may also use an [Azure VM](https://docs.microsoft.com/en-us/azure/virtual-machines/windows/quick-create-cli). In any case, you will need these software installed: - Packer 1.8.2 or higher. Download and install it manually from [here](https://www.packer.io/downloads) or use [Chocolatey](https://chocolatey.org/): ```powershell choco install packer ``` - Git. For Linux - install the latest version from your distro's package repo. For Windows - download and install it from [here](https://gitforwindows.org/) or use [Chocolatey](https://chocolatey.org/): ```powershell choco install git -params '"/GitAndUnixToolsOnPath"' ``` - Powershell 5.0 or higher. In Windows you already have it. For Linux follow instructions [here](https://learn.microsoft.com/en-us/windows-server/administration/linux-package-repository-for-microsoft-software) to add Microsoft's Linux Software Repository and then install the `powershell` package. - Azure CLI. Follow the instructions [here](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli). Or if you use Windows, you may run this command in Powershell instead: ```powershell Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile .\AzureCLI.msi Start-Process msiexec.exe -Wait -ArgumentList '/I AzureCLI.msi /quiet'; rm .\AzureCLI.msi ``` ## Manual image generation This repository includes a script that assists in generating images in Azure. All you need is an Azure subscription, a resource group in that subscription and a build agent configured as described above. All the commands below should be executed in PowerShell. First, clone the runner-images repository and set the current directory to it: ```powershell git clone https://github.com/actions/runner-images.git Set-Location runner-images ``` Then, import the [GenerateResourcesAndImage](../helpers/GenerateResourcesAndImage.ps1) script from the `helpers` subdirectory: ```powershell Import-Module .\helpers\GenerateResourcesAndImage.ps1 ``` Finally, run the `GenerateResourcesAndImage` function, setting the mandatory arguments: image type and where to build and store the resulting managed image: - `SubscriptionId` - your Azure Subscription ID; - `ResourceGroupName` - the name of the resource group that will store the resulting artifact (e.g., "imagegen-test"). The resource group must already exist in your Azure subscription; - `AzureLocation` - the location where resources will be created (e.g., "East US"); - `ImageType` - the type of image to build (valid options are "Windows2022", "Windows2025", "Windows2025_vs2026", "Ubuntu2204", "Ubuntu2404", "Ubuntu2604"). This function automatically creates all required Azure resources and initiates the Packer image generation for the selected image type. When the image is ready, you may proceed to [deployment](#generated-machine-deployment). ## Manual Image Generation Customization The `GenerateResourcesAndImage` function accepts a number of arguments that may assist you in generating an image in your specific environment. For example, you may want all the resources involved in the image generation process to be tagged. In this case, pass a HashTable of tags as a value for the `Tags` parameter. If you don't want the function to authenticate interactively, you should create a Service Principal and invoke the function with the parameters `AzureClientId`, `AzureClientSecret` and `AzureTenantId`. You can find more details in the [corresponding section below](#azure-subscription-authentication). Use `get-help GenerateResourcesAndImage -Detailed` for the complete list of available parameters. ### Network Security To connect to a temporary virtual machine, Packer uses WinRM or SSH. If your build agent is located outside of the Azure subscription where the temporary VM is created, a public network interface and public IP address are used. Make sure that firewalls are configured properly and that WinRM (TCP port 5986) and SSH (TCP port 22) connections are allowed both outgoing for the build agent and incoming for the temporary VM. Also, if you don't want the temporary VM to be accessible from everywhere, set the `RestrictToAgentIpAddress` parameter value to `$true` to set up firewall rules allowing access only from your build agent's public IP address. If your build agent and temporary VM are in the same subscription, you can configure Packer to connect using a private virtual network. To achieve this, set proper values for the environment variables `VNET_RESOURCE_GROUP`, `VNET_NAME` and `VNET_SUBNET`. ### Azure Subscription Authentication Packer uses a Service Principal to authenticate in Azure infrastructure. For more information about Service Principals, refer to the [Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal). The `GenerateResourcesAndImage` function is able to create a Service Principal to be used by Packer. It uses the Connect-AzAccount cmdlet that invokes an interactive authentication process by default. If you don't want to use interactive authentication, you should create a Service Principal with full read-write permissions for the selected Azure subscription on your own and provide proper values for the parameters `AzureClientId`, `AzureClientSecret` and `AzureTenantId`. Here is an example of how to create a Service Principal using the Az PowerShell module: ```powershell $credentials = [Microsoft.Azure.PowerShell.Cmdlets.Resources.MSGraph.Models.ApiV10.MicrosoftGraphPasswordCredential]@{ StartDateTime = Get-Date EndDateTime = (Get-Date).AddDays(7) } $sp = New-AzADServicePrincipal -DisplayName "imagegen-app" $appCred = New-AzADAppCredential -ApplicationId $sp.AppId -PasswordCredentials $credentials Start-Sleep -Seconds 30 New-AzRoleAssignment -RoleDefinitionName "Contributor" -PrincipalId $sp.Id Start-Sleep -Seconds 30 @{ ClientId = $sp.AppId ClientSecret = $appCred.SecretText TenantId = (Get-AzSubscription -SubscriptionId $SubscriptionId).TenantId } ``` ## Generated Machine Deployment After successful image generation, a Virtual Machine can be created from the generated image using the [CreateAzureVMFromPackerTemplate](../helpers/CreateAzureVMFromPackerTemplate.ps1) script. ```powershell Import-Module .\helpers\CreateAzureVMFromPackerTemplate.ps1 CreateAzureVMFromPackerTemplate -SubscriptionId {YourSubscriptionId} -ResourceGroupName {ResourceGroupName} -ManagedImageName "Runner-Image-Ubuntu2204" -VirtualMachineName "testvm1" -AdminUsername "shady1" -AdminPassword "SomeSecurePassword1" -AzureLocation "eastus" ``` Where: - `SubscriptionId` - the Azure subscription ID where resources will be created; - `ResourceGroupName` - the Azure resource group name where the Azure virtual machine will be created; - `ManagedImageName` - the name of the managed image to be used for the virtual machine creation; - `VirtualMachineName` - the name of the virtual machine to be generated; - `AdminUserName` - the administrator username for the virtual machine to be created; - `AdminPassword` - the administrator password for the virtual machine to be created; - `AzureLocation` - the location where the Azure virtual machine will be provisioned (e.g., "eastus"). This function creates an Azure VM and generates network resources in Azure to make the VM accessible. ## Automated image generation If you want to generate images automatically (e.g., as a part of a CI/CD pipeline), you can use Packer directly. To do this, you will need: - a build agent configured as described in the [Build agent preparation](#build-agent-preparation) section; - an Azure subscription and Service Principal configured as described in the [Azure subscription authentication](#azure-subscription-authentication) section; - a resource group created in your Azure subscription where the managed image will be stored; - a string to be used as a password for the user used to install software (Windows only). Then, you can invoke Packer in your CI/CD pipeline using the following commands: ```powershell packer plugins install github.com/hashicorp/azure 2.2.1 packer build -only "$BuildName.*" ` -var "subscription_id=$SubscriptionId" ` -var "client_id=$ClientId" ` -var "client_secret=$ClientSecret" ` -var "install_password=$InstallPassword" ` -var "location=$Location" ` -var "image_os=$ImageOS" ` -var "managed_image_name=$ImageName" ` -var "managed_image_resource_group_name=$ImageResourceGroupName" ` -var "tenant_id=$TenantId" ` $TemplatePath ``` Where: - `BuildName` - name of the build defined in Packer template's `build{}` block (e.g. "ubuntu-24_04", "windows-2025"); - `SubscriptionId` - your Azure Subscription ID; - `ClientId` and `ClientSecret` - Service Principal credentials; - `TenantId` - Azure Tenant ID; - `InstallPassword` - password for the user used to install software (Windows only); - `Location` - location where resources will be created (e.g., "East US"); - `ImageOS` - the type of OS that will be deployed as a temporary VM (e.g. "ubuntu24", "win25"); - `ImageName` and `ImageResourceGroupName` - name of the resource group where the managed image will be stored; - `TemplatePath` - path to the folder with Packer template files (e.g., "images/windows/templates"). ### Required variables The following variables are required to be passed to the Packer process: | Template var | Env var | Description | ------------ | ------- | ----------- | `subscription_id` | `ARM_SUBSCRIPTION_ID` | The subscription under which the build will be performed. | `client_id` | `ARM_CLIENT_ID` | The Active Directory service principal associated with your builder. | `client_secret` | `ARM_CLIENT_SECRET` | The password or secret for your service principal; may be omitted if `client_cert_path` or `client_jwt` is set. | `client_cert_path` | `ARM_CLIENT_CERT_PATH` | The location of a PEM file containing a certificate and private key for the service principal; may be omitted if `client_secret` or `client_jwt` is set. | `client_jwt` | `ARM_CLIENT_JWT` | A bearer JWT assertion for federated/workload identity authentication (e.g. Azure DevOps workload identity federation); may be omitted if `client_secret` or `client_cert_path` is set. | `location` | `ARM_RESOURCE_LOCATION` | The Azure datacenter in which your VM will be built. | `managed_image_resource_group_name` | `ARM_RESOURCE_GROUP` | The resource group under which the final artifact will be stored. ### Optional variables The following variables are optional: - `managed_image_name` - the name of the managed image to create. If not specified, "Runner-Image-{{ImageType}}" will be used; - `build_resource_group_name` - specify an existing resource group to run the build in; by default, a temporary resource group will be created and destroyed as part of the build; if you do not have permission to do so, use `build_resource_group_name` to specify an existing resource group to run the build in; - `object_id` - the object ID for the AAD SP; will be derived from the oAuth token if empty; - `tenant_id` - the Active Directory tenant identifier with which your `client_id` and `subscription_id` are associated; if not specified, `tenant_id` will be looked up using `subscription_id`; - `temp_resource_group_name` - the name assigned to the temporary resource group created during the build; if this value is not set, a random value will be assigned; this resource group is deleted at the end of the build; - `private_virtual_network_with_public_ip` - this value allows you to set a `virtual_network_name` and obtain a public IP; if this value is not set and `virtual_network_name` is defined, Packer is only allowed to be executed from a host on the same subnet / virtual network; - `virtual_network_name` - use a pre-existing virtual network for the VM; this option enables private communication with the VM, no public IP address is used or provisioned (unless you set `private_virtual_network_with_public_ip`); - `virtual_network_resource_group_name` - if `virtual_network_name` is set, this value may also be set; if `virtual_network_name` is set, and this value is not set, the builder attempts to determine the resource group containing the virtual network; if the resource group cannot be found, or it cannot be disambiguated, this value should be set; - `virtual_network_subnet_name` - if `virtual_network_name` is set, this value may also be set; if `virtual_network_name` is set, and this value is not set, the builder attempts to determine the subnet to use with the virtual network; if the subnet cannot be found, or it cannot be disambiguated, this value should be set. ## Builder variables The `builders` section contains variables for the `azure-arm` builder used in the project. Most of the builder variables are inherited from the `user variables` section, however, the variables can be overwritten to adjust image-generation performance. - `vm_size` - the size of the VM used for building; this can be changed when you deploy a VM from your image; - `image_os` - the type of OS that will be deployed as a temporary VM; - `image_version` - specify the version of an OS to boot from. **Detailed Azure builders documentation can be found in the [packer documentation](https://www.packer.io/docs/builders/azure).** ## Toolset The configuration for some installed software is located in `toolset.json` files. These files define the list of Ruby, Python, Go versions, the list of PowerShell modules and VS components that will be installed on the image. They can be changed if these tools are not required, to reduce image generation time or image size. Generated tool versions and details can be found in related projects: - [Python](https://github.com/actions/python-versions/) - [Go](https://github.com/actions/go-versions) - [Node](https://github.com/actions/node-versions) ## Post-generation scripts > :warning: These scripts are intended to be run on a VM deployed in Azure The user, created during the image generation, does not exist in the resulting image. Hence, some configuration files related to the user's home directory need to be changed, as well as the file permissions for some directories. Scripts for that are located in the `post-gen` folder in the repository: - Windows: - Linux: **Note:** The default user for Linux should have `sudo privileges`. The scripts are copied to the image during the generation process to the following paths: - Windows: `C:\post-generation` - Linux: `/opt/post-generation` ### Running scripts - Ubuntu ```bash sudo su -c "find /opt/post-generation -mindepth 1 -maxdepth 1 -type f -name '*.sh' -exec bash {} \;" ``` - Windows ```powershell Get-ChildItem C:\post-generation -Filter *.ps1 | ForEach-Object { & $_.FullName } ``` ### Script Details: Ubuntu - **cleanup-logs.sh** - removes all build process logs from the machine; - **environment-variables.sh** - replaces `$HOME` with the default user's home directory for environment variables related to the default user home directory; - **homebrew-permissions.sh** - resets the Homebrew repository directory by running `git reset --hard` to make the working tree clean after changing permissions in /home and changes the repository directory owner to the current user; - **rust-permissions.sh** - fixes permissions for the Rust folder; a detailed issue explanation is provided in [runner-images/issues/572](https://github.com/actions/runner-images/issues/572). ### Script Details: Windows - **GenerateIISExpressCertificate.ps1** - generates and imports a certificate to run applications with IIS Express through HTTPS; - **InternetExplorerConfiguration.ps1** - turns off the Internet Explorer Enhanced Security feature; - **Msys2FirstLaunch.ps1** - initializes the bash user profile in MSYS2; - **VSConfiguration.ps1** - performs initial Visual Studio configuration. --- ## File: docs/dotnet-ubuntu.md # Ubuntu .NET Core Versions .NET has changed the recommended install methods for Ubuntu from 2404. This document gives an overview of these change and the impact this has on the `runner-images`. ## .NET Core for Ubuntu 2204 2204 uses the [Microsoft Package repository](https://learn.microsoft.com/en-us/dotnet/core/install/linux-ubuntu-install?tabs=dotnet8&pivots=os-linux-ubuntu-2204) to install .NET deb files built and published by the .NET team. ## .NET Core Versions from Ubuntu 2404 The .NET Core team have worked with Canonical and Ubuntu now provides its own .NET packages. These are the recommended install path and, as-such what is installed on the image. > The release of Ubuntu 24.04 is just around the corner. Canonical-produced .NET 6, 7, and 8 packages will be available on day one, for "Noble Numbat". Microsoft will not be publishing .NET packages to the 24.04 feed at packages.microsoft.com. You can read the [full announcement from .NET team here](https://github.com/dotnet/core/discussions/9258). We'll briefly summarize how this change may impact users of the image. ### [`Feature Bands`](https://learn.microsoft.com/dotnet/core/porting/versioning-sdk-msbuild-vs) Going forward only the `1xx` feature band will be present in the image as Ubuntu only build and publish this band. > Most distros, including Ubuntu, stick to the .1xx feature band for the lifetime of a major .NET version. They make this choice because .1xx is (effectively) the "compatibility band". Higher bands can have breaking changes. > This means there will no longer be packages available for .2xx and later feature bands. Such packages have been exclusively available from Microsoft. If users see an incompatibility between .1xx and higher feature bands, we ask that you please report it in the dotnet/sdk repo. [link: dotnet/core discussion](https://github.com/dotnet/core/discussions/9258) If you need a higher feature band for your Actions the recommendation is to use the [`setup-dotnet`](https://github.com/actions/setup-dotnet) action to install the desired version. ### .NET MAUI .NET MAUI is [not included](https://github.com/dotnet/core/discussions/9258#discussioncomment-9548857) in the Ubuntu .NET package. There is work [ongoing to fix.](https://github.com/dotnet/core/discussions/9258#discussioncomment-9548857) You should be able to resolve this by using the [`setup-dotnet`](https://github.com/actions/setup-dotnet) action to install the desired version. --- ## File: images/macos/toolsets/Readme.md # Toolset JSON structure ## Xcode - `versions` - the array of objects that will present installed Xcode versions - `link` property points to the place where Xcode will be located on image. `/Applications/Xcode_.app` - `version` points to Xcode version that will be downloaded and installed - `symlinks` describes the list of aliases where symlinks will be created to - `sha256` used to check integrity of the Xcode installer file - `install_runtimes` – controls the installation of simulator runtimes: - `default` – installs all default runtimes. - `none` – skips runtime installation. - **Hashtable** – allows manual selection: - Mandatory keys: `[ "iOS", "watchOS", "tvOS" ]`, plus `visionOS` for arm64 images. - Values [array of string]: - `"default"` – installs the default runtime. - `"skip"` – skips installation. - Specific version numbers, e.g., `"18.2"`, `"2.2"`, `"18.3.1"`. - Apple release version, e.g., `"22E5216h"`, `"17A577"`. - `default` - version of Xcode to set as default (should be matched with any `link` in `versions` property) **Example:** `"11.2"` **Note:** - `version` is specified with `+` or `-`, exact Xcode name should be like `16.2.0-Beta.3+16C5023f` or `16.2_Release_Candidate+16C5031c` and will be matching `.xip` file name. - `link` is specified with `_` and doesn't contain spaces, example: `16.2_Release_Candidate` or `16.1`; pattern description: - DOWNLOAD_URL="https://download.developer.apple.com/Developer_Tools/$SOURCE_FILE_LOCATION/$SOURCE_FILE_NAME.$FILE_EXTENSION" - SOURCE_FILE_NAME: "Xcode_$link" - SOURCE_FILE_LOCATION: "Xcode_$link" - FILE_EXTENSION: xip **Example:** String format: ```json "versions": [ { "link": "16_beta_4", "version": "16.0.0-Beta.4+16A5211f", "symlinks": ["16.0"], "install_runtimes": "none", "sha256": "4270cd8021b2f7f512ce91bfc4423b25bccab36cdab21834709d798c8daade72"}, { "link": "15.4", "version": "15.4.0+15F31d", "install_runtimes": "default", "sha256": "82d3d61804ff3f4c7c82085e91dc701037ddaa770e542848b2477e22f4e8aa7a"} ] ``` Block format: ```json "versions": [ { "link": "16.2", "version": "16.2+16C5032a", "sha256": "0e367d06eb7c334ea143bada5e4422f56688aabff571bedf0d2ad9434b7290de", "install_runtimes": [ { "iOS": ["18.0", "18.1", "18.2"] }, { "watchOS": "default" }, { "tvOS": "default" }, { "visionOS": "2.2" } ] }, { "link": "16.1", "version": "16.1+16B40", "sha256": "8ca961d55981f983d21b99a95a6b0ac04905b837f6e11346ee86d28f12afe720", "install_runtimes": "default" } ] ``` ## Android - `platform-list` - the array of android platforms to install. **Example:** `[ "android-29", "android-28", "android-27" ]` - `build-tools` - the array of android build tools to install. **Example:** `[ "29.0.2", "29.0.1", "29.0.0", "28.0.3" ]` - `extras` - the array of android extra items to install. **Example:** `[ "google;google_play_services", "intel;Hardware_Accelerated_Execution_Manager" ]` - `addons` - the array of android add-ons to install. **Example:** `[ "addon-google_apis-google-24", "addon-google_apis-google-23" ]` ## Toolset JSON validation File `Toolset.Tests.ps1` contains PowerShell [Pester](https://github.com/Pester/Pester) tests that validate JSON toolset files. Type `Invoke-Pester` in the current folder in PowerShell to run tests.