From 51e536326f6690aab998addb96f4013a8baad960 Mon Sep 17 00:00:00 2001 From: Paulo Santos Date: Thu, 20 Nov 2025 11:25:02 +0000 Subject: [PATCH 1/7] add copilot instructions for Github Actions runner-images repository --- .github/copilot-instructions.md | 35 +++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..cd2661674 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,35 @@ +# GitHub Copilot Instructions for Actions Runner Images Repository + +## Scope and goals +- This repository serves as the source for building Github Actions runner and Azure Dev Ops agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [README.md](../README.md#available-images) available images section. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization. +- Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette. +- Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing. + +# Code and command instructions +- Focus on following the style guide for [Powershell](https://github.com/PoshCode/PowerShellPracticeAndStyle) when writing Windows scripts. For shell scripts on Linux and macOS, maintain consistency with existing scripts. +- Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation. +- Always confirm versions and installations paths against existing toolset files and installation scripts. +- Refer to [Contributing.md](../CONTRIBUTING.md) for extended guidelines on contributing to this repository. + +## Output format +- Use GitHub Flavored Markdown only. Avoid raw HTML unless necessary. +- One H1 (`#`) per page, followed by logical, sequential headings (`##`, `###`, …). +- Use fenced code blocks with language identifiers (```bash, ```json, ```yaml, etc.). +- Use blockquote callouts for notes: + > [!NOTE] Context or nuance + > [!TIP] Helpful hint + > [!WARNING] Risks or breaking changes + > [!IMPORTANT] Critical requirement for functionality + +## Style and tone +- Audience: Open-source contributors, GitHub Actions maintainers, and developers building custom runner images. Assume familiarity with CI/CD concepts, Packer, and basic infrastructure provisioning, but explain platform-specific details (Azure for Windows/Ubuntu, Anka for macOS) when relevant. +- Voice: Second person ("you"), active voice, imperative for operational steps. +- Be concise: short paragraphs and sentences. Prefer lists and step-by-steps, especially for operational procedures and troubleshooting. +- Use inclusive, accessible language. Avoid idioms, sarcasm, and culturally specific references. +- English: en-US (spelling, punctuation, and units). + +## Safety and integrity +- Do not expose sensitive credentials (API tokens, Azure subscription IDs, etc.) in code examples. +- Do not fabricate tool versions, installation paths, or software availability without verifying against toolset files or actual installation scripts. +- Always call out assumptions and limitations explicitly, especially for changes affecting runner image behavior or software availability. +- If ambiguous requests are made about image modifications, ask clarifying questions about target OS, tool versions, and compatibility requirements before proceeding. From f5d8f202e73da8e67ad9bf25e3e32964674192ef Mon Sep 17 00:00:00 2001 From: Paulo Santos Date: Thu, 20 Nov 2025 11:39:16 +0000 Subject: [PATCH 2/7] lint: applied markdown linting --- .github/copilot-instructions.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index cd2661674..170f4dda1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,20 +1,23 @@ # GitHub Copilot Instructions for Actions Runner Images Repository ## Scope and goals + - This repository serves as the source for building Github Actions runner and Azure Dev Ops agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [README.md](../README.md#available-images) available images section. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization. - Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette. - Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing. -# Code and command instructions +## Code and command instructions + - Focus on following the style guide for [Powershell](https://github.com/PoshCode/PowerShellPracticeAndStyle) when writing Windows scripts. For shell scripts on Linux and macOS, maintain consistency with existing scripts. - Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation. - Always confirm versions and installations paths against existing toolset files and installation scripts. - Refer to [Contributing.md](../CONTRIBUTING.md) for extended guidelines on contributing to this repository. ## Output format + - Use GitHub Flavored Markdown only. Avoid raw HTML unless necessary. - One H1 (`#`) per page, followed by logical, sequential headings (`##`, `###`, …). -- Use fenced code blocks with language identifiers (```bash, ```json, ```yaml, etc.). +- Use fenced code blocks with language identifiers (` ```bash `, ` ```json `, ` ```yaml `, etc.). - Use blockquote callouts for notes: > [!NOTE] Context or nuance > [!TIP] Helpful hint @@ -22,6 +25,7 @@ > [!IMPORTANT] Critical requirement for functionality ## Style and tone + - Audience: Open-source contributors, GitHub Actions maintainers, and developers building custom runner images. Assume familiarity with CI/CD concepts, Packer, and basic infrastructure provisioning, but explain platform-specific details (Azure for Windows/Ubuntu, Anka for macOS) when relevant. - Voice: Second person ("you"), active voice, imperative for operational steps. - Be concise: short paragraphs and sentences. Prefer lists and step-by-steps, especially for operational procedures and troubleshooting. @@ -29,6 +33,7 @@ - English: en-US (spelling, punctuation, and units). ## Safety and integrity + - Do not expose sensitive credentials (API tokens, Azure subscription IDs, etc.) in code examples. - Do not fabricate tool versions, installation paths, or software availability without verifying against toolset files or actual installation scripts. - Always call out assumptions and limitations explicitly, especially for changes affecting runner image behavior or software availability. From c5a12a401adfca2cdfd061af826fc47d5cba0073 Mon Sep 17 00:00:00 2001 From: Paulo Santos Date: Thu, 20 Nov 2025 11:41:04 +0000 Subject: [PATCH 3/7] copilot: spelling correction Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 170f4dda1..1eb798232 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ ## Scope and goals -- This repository serves as the source for building Github Actions runner and Azure Dev Ops agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [README.md](../README.md#available-images) available images section. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization. +- This repository serves as the source for building GitHub Actions runner and Azure DevOps agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [README.md](../README.md#available-images) available images section. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization. - Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette. - Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing. From 45c63aafc45a7bc181bb80a4b6fc52f6f376a231 Mon Sep 17 00:00:00 2001 From: Paulo Santos Date: Thu, 27 Nov 2025 01:38:02 +0000 Subject: [PATCH 4/7] add style guide to CONTRIBUTING.md --- CONTRIBUTING.md | 190 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 188 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9f9547a45..3f9ed145e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,11 +10,18 @@ Contributions to this project are [released](https://help.github.com/articles/gi Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project, you agree to abide by its terms. +## Contents + +- [Submitting a pull request](#submitting-a-pull-request) +- [Adding a new tool to an image](#adding-a-new-tool-to-an-image) +- [Code style guide](#code-style-guide) + + ## Submitting a pull request 1. [Fork][fork] and clone the repository. 1. Create a new branch: `git checkout -b my-branch-name`. -1. Make your changes, ensuring that they include steps to install, validate post-install, and update the software report (please see [How to add a new tool](CONTRIBUTING.md#how-to-add-a-new-tool) for details). +1. Make your changes, ensuring that they include steps to install, validate post-install, and update the software report (please see [Adding a new tool to an image](#adding-a-new-tool-to-an-image) for details). 1. Test your changes by [creating an image and deploying a VM](docs/create-image-and-azure-resources.md). 1. Push to your fork and [submit a pull request][pr]. @@ -28,7 +35,7 @@ Here are a few things you can do that will increase the likelihood of your pull - Make sure that the tool satisfies the [Software Guidelines](README.md#software-guidelines). - Create an issue and get approval from us to add this tool to the image before creating the pull request. -## How to add a new tool +## Adding a new tool to an image ### General rules @@ -60,6 +67,185 @@ Use existing scripts such as [github-cli.sh](images/ubuntu/scripts/build/github- The macOS source lives in this repository and is available for everyone. However, the 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 the macOS CI to accept contributions. Until then, we appreciate your patience and ask that you continue to make tool requests by filing issues. +## Code style guide + +The principles of clean code apply to all languages. The main points are: + +- Use meaningful names for variables, functions, files, etc. +- Keep functions short and simple. +- Use comments to explain what the code does. +- Use a consistent code style, naming convention, and file structure. + +### File structure + +- Each file should have a header with a title and a short description of the file. +- Each file should have a newline at the end. +- Use blank lines to separate logical blocks of code, but don't abuse blank lines: + - Don't add a blank line in the beginning and end of a block or function. + - Don't add blank lines between logically connected statements. +- Avoid trailing whitespace. + +### Bash scripts + +#### Naming convention for bash scripts + +- Use lowercase letters for variable names. +- Use uppercase letters for constants. +- Use underscores to separate words in variable names. + +#### Bash script structure + +Each script should start with the following shebang: + +```bash +#!/bin/bash -e +``` + +> TODO: do we need to set pipefail? + +This will make the script exit if any command fails. + +After the shebang, add a header with of the following format: + +```bash +################################################################################ +## File: +## Desc: +################################################################################ +``` + +Then import helpers that are used in the script. + +For Linux: + +```bash +source $HELPER_SCRIPTS/os.sh +source $HELPER_SCRIPTS/install.sh +source $HELPER_SCRIPTS/etc-environment.sh +``` + +For mac OS: + +```bash +source ~/utils/utils.sh +``` + +> [!NOTE] +> You don't need to import all helpers, only the ones that are used in the script. + +After that, add the script code. + +### Indentations and line breaks in bash scripts + +- Use 4 spaces for indentation. +- Use 1 space between `if`/`for`/`while` and `[[` and between `[[` and the condition. +- Place `then`/`do` on the new line. +- For short `if`/`for`/`while` statements, use the one-line format. +- Break long pipelines using `\`. + +### Other recommendations for bash scripts + +- For command substitution, use `$()` instead of backticks. +- Use `[[` instead of `[` for conditional expressions. +- Prefer using long options instead of short keys, but there are exceptions, e.g.: + - `tar -xzf` + - `apt-get -yqq` + - `curl -sSLf` + - `wget -qO-` + +### Powershell scripts + +#### Naming convention for Powershell scripts + +- Use camelCase for variable names. +- Use uppercase letters for constants. +- Use `Verb-Noun` and PascalCase for function names. + +### Powershell script structure + +Each script should start with the following header: + +```powershell +################################################################################ +## File: +## Desc: +################################################################################ +``` + +Then declare functions that are used in the script. + +> TODO: do we need to set the error action preference and progress preference? +> +> ```powershell +> $ErrorActionPreference = "Stop" +> $ProgressPreference = "SilentlyContinue" +> ``` + +For Linux and mac OS, import helpers that are used in the script: + +For Linux: + +```powershell +Import-Module "$env:HELPER_SCRIPTS/Tests.Helpers.psm1" -DisableNameChecking +``` + +For mac OS: + +```powershell +Import-Module "$env:HOME/image-generation/helpers/Common.Helpers.psm1" +Import-Module "$env:HOME/image-generation/helpers/Xcode.Helpers.psm1" -DisableNameChecking +``` + +> [!NOTE] +> You don't need to import all helpers, only the ones that are used in the script. + +After that, add the script code. + +### Indentations and line breaks in Powershell scripts + +- Use 4 spaces for indentation. +- Use 1 space between `if`/`elseif`/`foreach` and `(` but not between `(` and the condition. +- Add a space before and after pipe `|` and redirection `>` operators. +- Align properties in hash tables. +- Use [1TBS](https://en.wikipedia.org/wiki/Indentation_style#Variant:_1TBS_(OTBS)) style for curly braces: + - If block of statement is long, then place it on the new line, indent it, and add a closing curly brace on the new line. + - If block of statement is short, then place it on the same line as the statement. + + ```powershell + function Show-Example1 { + $exampleVariable = Get-ChildItem $env:TEMP + $exampleVariable | ForEach-Object { + $itemName = $_.Name + $itemPath = $_.FullName + } + } + + $Example2 | Some-Function -Arguments @{Parameter1 = "Disabled"} + ``` + +- Avoid using aliases. +- Break long pipelines using backticks or use [splatting](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_splatting?view=powershell-7.3): + + ```powershell + # Instead of this + Copy-Item -Path "test.txt" -Destination "test2.txt" -WhatIf + + # you can use this + $HashArguments = @{ + Path = "test.txt" + Destination = "test2.txt" + WhatIf = $true + } + Copy-Item @HashArguments + ``` + + When using backticks be extra careful with trailing whitespace as they can cause errors. + +### Other recommendations for PowerShell scripts + +- Verify exit codes of commands. +- When writing a function, provide a docstring that describes what the function does. + ## Resources - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) From 9b1fa5a76cd0fb2fcf0d2b86a7ae5fbe2ace2856 Mon Sep 17 00:00:00 2001 From: Paulo Santos Date: Thu, 27 Nov 2025 01:41:57 +0000 Subject: [PATCH 5/7] update copilot code instructions to refer to CONTRIBUTING.md --- .github/copilot-instructions.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1eb798232..0dc4a7d2d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,10 +8,9 @@ ## Code and command instructions -- Focus on following the style guide for [Powershell](https://github.com/PoshCode/PowerShellPracticeAndStyle) when writing Windows scripts. For shell scripts on Linux and macOS, maintain consistency with existing scripts. +- Follow the code style guide in [CONTRIBUTING.md](../CONTRIBUTING.md#code-style-guide) for Bash and PowerShell scripts, including naming conventions, file structure, and indentation rules. - Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation. - Always confirm versions and installations paths against existing toolset files and installation scripts. -- Refer to [Contributing.md](../CONTRIBUTING.md) for extended guidelines on contributing to this repository. ## Output format From 868bc6b53cc0157f8e5259e3ffaf322bf978f9f4 Mon Sep 17 00:00:00 2001 From: Erik Bershel <110455084+erik-bershel@users.noreply.github.com> Date: Thu, 27 Nov 2025 13:24:50 +0100 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 4 ++-- CONTRIBUTING.md | 12 ++++++------ 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0dc4a7d2d..3e75a0acc 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,7 +2,7 @@ ## Scope and goals -- This repository serves as the source for building GitHub Actions runner and Azure DevOps agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [README.md](../README.md#available-images) available images section. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization. +- This repository serves as the source for building GitHub Actions runner and Azure DevOps agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [Available Images](../README.md#available-images) section of README.md. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization. - Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette. - Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing. @@ -10,7 +10,7 @@ - Follow the code style guide in [CONTRIBUTING.md](../CONTRIBUTING.md#code-style-guide) for Bash and PowerShell scripts, including naming conventions, file structure, and indentation rules. - Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation. -- Always confirm versions and installations paths against existing toolset files and installation scripts. +- Always confirm versions and installation paths against existing toolset files and installation scripts. ## Output format diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f9ed145e..0484bb27e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -105,7 +105,7 @@ Each script should start with the following shebang: This will make the script exit if any command fails. -After the shebang, add a header with of the following format: +After the shebang, add a header with the following format: ```bash ################################################################################ @@ -124,7 +124,7 @@ source $HELPER_SCRIPTS/install.sh source $HELPER_SCRIPTS/etc-environment.sh ``` -For mac OS: +For macOS: ```bash source ~/utils/utils.sh @@ -153,15 +153,15 @@ After that, add the script code. - `curl -sSLf` - `wget -qO-` -### Powershell scripts +### PowerShell scripts -#### Naming convention for Powershell scripts +#### Naming convention for PowerShell scripts - Use camelCase for variable names. - Use uppercase letters for constants. - Use `Verb-Noun` and PascalCase for function names. -### Powershell script structure +### PowerShell script structure Each script should start with the following header: @@ -201,7 +201,7 @@ Import-Module "$env:HOME/image-generation/helpers/Xcode.Helpers.psm1" -DisableNa After that, add the script code. -### Indentations and line breaks in Powershell scripts +### Indentations and line breaks in PowerShell scripts - Use 4 spaces for indentation. - Use 1 space between `if`/`elseif`/`foreach` and `(` but not between `(` and the condition. From df2584718f800b00260ca09afbc2b765d6abd271 Mon Sep 17 00:00:00 2001 From: Erik Bershel <110455084+erik-bershel@users.noreply.github.com> Date: Thu, 27 Nov 2025 13:26:35 +0100 Subject: [PATCH 7/7] Apply suggestions from code review --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0484bb27e..eddd7d5b8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -181,7 +181,7 @@ Then declare functions that are used in the script. > $ProgressPreference = "SilentlyContinue" > ``` -For Linux and mac OS, import helpers that are used in the script: +For Linux and macOS, import helpers that are used in the script: For Linux: @@ -189,7 +189,7 @@ For Linux: Import-Module "$env:HELPER_SCRIPTS/Tests.Helpers.psm1" -DisableNameChecking ``` -For mac OS: +For macOS: ```powershell Import-Module "$env:HOME/image-generation/helpers/Common.Helpers.psm1"