mirror of
https://github.com/actions/runner-images.git
synced 2025-12-11 03:27:05 +00:00
Virtual environment rebrand - readme updates (#6006)
* Create release-preview.md
* Update release-preview.md
* Update release-preview.md
* Update release-preview.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* Update README.md
* update support policy wording
* Update README.md
* Preparing for upstream PR
deleted a test file I made
* fixing some linting errors
* Update README.md
* Apply suggestions from code review
Co-authored-by: Mikhail Timofeev <48208649+miketimofeev@users.noreply.github.com>
* Updating per PR suggestions
* Delete software-and-images-guidelines.md
* Updates per Steve's suggestion
* Update README.md
* Apply suggestions from code review
Co-authored-by: Sam Tran <samvantran@github.com>
* Update README.md
* Revert "Update README.md"
This reverts commit 9ff7d224e3.
* docs: fix markdownlint errors
Co-authored-by: Mikhail Timofeev <48208649+miketimofeev@users.noreply.github.com>
Co-authored-by: Sam Tran <samvantran@github.com>
This commit is contained in:
Larissa Fortuna
206
README.md
206
README.md
@@ -1,52 +1,38 @@
|
||||
# GitHub Actions Virtual Environments
|
||||
Repository contains the source used to create the [virtual environments](https://help.github.com/en/actions/reference/virtual-environments-for-github-hosted-runners) for GitHub Actions hosted runners, as well as the VM images of [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.
|
||||
|
||||
# GitHub Actions Runner Images
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
- [About](#about)
|
||||
- [Available Images](#available-images)
|
||||
- [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).
|
||||
|
||||
How to get in touch with us:
|
||||
- To file a bug report, or request tools to be added/updated, please [open an issue using the appropriate template](https://github.com/actions/virtual-environments/issues/new/choose)
|
||||
- If you want to share your thoughts about image configuration, installed software, or bring some idea, please, create a new topic in a [discussions section](https://github.com/actions/virtual-environments/discussions) for a corresponding category. Before making a new discussion please make sure no similar topics were created earlier.
|
||||
## Available Images
|
||||
|
||||
For general questions about using the virtual environments or writing your Actions workflow, please open requests in the [GitHub Actions Community Forum](https://github.community/c/github-actions/41).
|
||||
|
||||
## Available Environments
|
||||
| Environment | YAML Label | Included Software | Latest Release & Rollout Progress |
|
||||
| Image | YAML Label | Included Software | Rollout Progress of Latest Image Release |
|
||||
| --------------------|---------------------|--------------------|---------------------|
|
||||
| Ubuntu 22.04 <sup>beta</sup> | `ubuntu-22.04` | [ubuntu-22.04] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=ubuntu22&redirect=1)
|
||||
| Ubuntu 20.04 | `ubuntu-latest` or `ubuntu-20.04` | [ubuntu-20.04] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=ubuntu20&redirect=1)
|
||||
| Ubuntu 18.04 | `ubuntu-18.04` | [ubuntu-18.04] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=ubuntu18&redirect=1)
|
||||
| macOS 12 | `macos-12`| [macOS-12] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=macos-12&redirect=1)
|
||||
| macOS 11 | `macos-latest` or `macos-11`| [macOS-11] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=macos-11&redirect=1)
|
||||
| macOS 10.15 <sup>deprecated</sup> | `macos-10.15` | [macOS-10.15] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=macos-10.15&redirect=1)
|
||||
| Windows Server 2022 | `windows-latest` or `windows-2022` | [windows-2022] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=windows-2022&redirect=1) |
|
||||
| Windows Server 2019 | `windows-2019` | [windows-2019] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=windows-2019&redirect=1)
|
||||
| Ubuntu 22.04 | `ubuntu-22.04` | [ubuntu-22.04] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=ubuntu22&redirect=1)
|
||||
| Ubuntu 20.04 | `ubuntu-latest` or `ubuntu-20.04` | [ubuntu-20.04] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=ubuntu20&redirect=1)
|
||||
| Ubuntu 18.04 <sup>deprecated</sup> | `ubuntu-18.04` | [ubuntu-18.04] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=ubuntu18&redirect=1)
|
||||
| macOS 12 | `macos-12`| [macOS-12] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=macos-12&redirect=1)
|
||||
| macOS 11 | `macos-latest` or `macos-11`| [macOS-11] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=macos-11&redirect=1)
|
||||
| macOS 10.15 <sup>deprecated</sup> | `macos-10.15` | [macOS-10.15] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=macos-10.15&redirect=1)
|
||||
| Windows Server 2022 | `windows-latest` or `windows-2022` | [windows-2022] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=windows-2022&redirect=1) |
|
||||
| Windows Server 2019 | `windows-2019` | [windows-2019] | [](https://actionvirtualenvironmentsstatus.azurewebsites.net/api/status?imageName=windows-2019&redirect=1)
|
||||
|
||||
<b>Note:</b> Beta and Preview images are provided "as-is", "with all faults" and "as available" and are excluded from the service level agreement and warranty. Beta and Preview images may not be covered by customer support.
|
||||
### Label scheme
|
||||
|
||||
***What images are available for GitHub Actions and Azure DevOps?***
|
||||
The availability of images for GitHub Actions and Azure DevOps is different. 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 3-4 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 virtual environments. Alternatively, you can leverage [self-hosted runners] and fully customize your environment to your needs.
|
||||
|
||||
***How to contribute to macOS source?*** macOS source lives in this repository and 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 continue to make tool requests by filing issues.
|
||||
|
||||
## Updates to virtual environments
|
||||
*Cadence*
|
||||
|
||||
We typically deploy weekly updates to the software on the virtual environments.
|
||||
For some tools, we always install the latest at the time of the deployment; for others,
|
||||
we pin the tool to specific version(s).
|
||||
|
||||
*Following Along / Change Notifications*
|
||||
|
||||
* **High Impact Changes** (ex. breaking changes, new or deprecated environments) will be posted to the GitHub Changelog on our [blog](https://github.blog/changelog/) and on [twitter](https://twitter.com/GHchangelog).
|
||||
* **Low Impact Changes** will be pinned in this repository and marked with the [Announcement](https://github.com/actions/virtual-environments/labels/Announcement) label.
|
||||
* **Regular Weekly Rhythm** can be followed by watching [Releases](https://github.com/actions/virtual-environments/releases). Pre-release is created when deployment is started. As soon as deployment is finished, it is converted to release.
|
||||
You can also track upcoming changes using the [awaiting-deployment](https://github.com/actions/virtual-environments/labels/awaiting-deployment) label.
|
||||
- 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
|
||||
|
||||
[ubuntu-22.04]: https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu2204-Readme.md
|
||||
[ubuntu-20.04]: https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu2004-Readme.md
|
||||
@@ -58,5 +44,135 @@ You can also track upcoming changes using the [awaiting-deployment](https://gith
|
||||
[macOS-10.15]: https://github.com/actions/virtual-environments/blob/main/images/macos/macos-10.15-Readme.md
|
||||
[self-hosted runners]: https://help.github.com/en/actions/hosting-your-own-runners
|
||||
|
||||
## Software and image guidelines
|
||||
To learn more about tools and images support policy, see the [guidelines](./docs/software-and-images-guidelines.md).
|
||||
## 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.
|
||||
|
||||
## Image Releases
|
||||
|
||||
*How to best follow along with changes*
|
||||
|
||||
1. Find the latest releases for this repository [here.](https://github.com/actions/virtual-environments/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/virtual-environments/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 [twitter](https://twitter.com/GHchangelog).
|
||||
- Ex: breaking changes, GA or deprecation of images
|
||||
5. You can also view notable upcoming changes by viewing the [Announcement](https://github.com/actions/virtual-environments/labels/Announcement) label.
|
||||
|
||||
*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 <br/> 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 |
|
||||
| GCC <br/> GNU Fortran <br/> Clang <br/> GNU C++ | 3 latest major versions |
|
||||
| Android NDK | 1 latest non-LTS, 2 latest LTS versions |
|
||||
| Xcode | - all OS compatible versions side-by-side <br/> - for beta, GM versions - latest beta only <br/> - old patch versions are deprecated in 3 months |
|
||||
|
||||
### 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/virtual-environments/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 topic in a [discussion](https://github.com/actions/virtual-environments/discussions) for a corresponding category. Before making a new discussion please make sure no similar topics were created earlier.
|
||||
- For general questions about using the runner images or writing your Actions workflow, please open requests in the [GitHub Actions Community Forum](https://github.community/c/github-actions/41).
|
||||
|
||||
## FAQs
|
||||
|
||||
<details>
|
||||
<summary><b><i>What images are available for GitHub Actions and Azure DevOps?</b></i></summary>
|
||||
|
||||
The availability of images for GitHub Actions and Azure DevOps is the same. However, deprecation polciies 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)
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b><i>What image version is used in my build?</b></i></summary>
|
||||
|
||||
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.
|
||||
<img width="1440" alt="actions-runner-image" src="https://user-images.githubusercontent.com/56982181/169595536-91a8a79b-d5e0-47d1-a736-510cff6cfb83.png">
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b><i>Looking for other Linux distributions?</b></i></summary>
|
||||
|
||||
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.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b><i>How do I contribute to the macOS source?</b></i></summary>
|
||||
|
||||
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.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b><i>How does GitHub determine what tools are installed on the images?</b></i></summary>
|
||||
|
||||
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)
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b><i>How do I request that a new tool be pre-installed on the image?</b></i></summary>
|
||||
Please create an issue and get an approval from us to add this tool to the image before creating the pull request.
|
||||
</details>
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
# Software and image guidelines
|
||||
|
||||
## Software preinstallation policy
|
||||
In general, these are the guidelines we consider when deciding what to pre-install:
|
||||
|
||||
- Tools and ecosystems that are broadly popular and widely-used will be given priority.
|
||||
- Recent versions of tools will be given priority over older versions.
|
||||
- Tools and versions that are deprecated or have reached end-of-life will not be added.
|
||||
- If a tool can be installed during the build, we will evaluate how much time is saved
|
||||
and how much space is used by having the tool pre-installed.
|
||||
- MIT, Apache, and GNU licenses are ok, anything else we'll have to check with lawyers.
|
||||
- If a tool takes much space we will evaluate space usage and provide a decision if this tool can be pre-installed.
|
||||
- If a tool requires the support of more than one version, we will consider the cost of this maintenance, how often new versions bring dangerous updates.
|
||||
|
||||
**Note:** For new tools, please, create an issue and get an approval from us to add this tool to the image before creating the pull request.
|
||||
|
||||
## Software and images support policy
|
||||
These are the guidelines we follow in software and images supporting routine:
|
||||
- Tools and versions will typically be removed 6 months after they are deprecated or have reached end-of-life.
|
||||
- We support at least 2 latest OS versions. We begin the deprecation process of the oldest image label once a new OS version has been released.
|
||||
- The images generally contain the latest versions of packages installed except for Ubuntu LTS where we rely on the Canonical-provided repositories mostly.
|
||||
- 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 <br/> 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 |
|
||||
| GCC <br/> GNU Fortran <br/> Clang <br/> GNU C++ | 3 latest major versions |
|
||||
| Android NDK | 1 latest non-LTS, 2 latest LTS versions |
|
||||
| Xcode | - all OS compatible versions side-by-side <br/> - for beta, GM versions - latest beta only <br/> - old patch versions are deprecated in 3 months |
|
||||
|
||||
## Software default versions update policy for tools with multiple versions installed
|
||||
In general, once a new version is installed on the image, we announce the default version update 2 weeks prior to deploying it to give time to adapt to upcoming changes. For potentially dangerous updates, we can extend the timeline up to 1 month between the announcement and deployment.
|
||||
Reference in New Issue
Block a user