Skip to content

Update docs for GoTool@0, update quick start #2139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dagood wants to merge 2 commits into
base: microsoft/main
Choose a base branch
from
+33 −13
Open

Update docs for GoTool@0, update quick start #2139

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
44fda99
Update docs for GoTool@0, update quick start
dagood Feb 13, 2026
3ee1876
Fix GoTool@0 section link
dagood Feb 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,10 +109,10 @@ After the repository is added, install the Microsoft build of Go by running the
sudo apt-get update && sudo apt-get install msft-golang
```

### Binary archive
### Azure Pipelines `GoTool@0` task

[Signed builds of Go](https://github.com/microsoft/go/blob/microsoft/main/eng/doc/Downloads.md)
for several platforms are available as `zip` and `tar.gz` files.
The [`GoTool@0`](https://learn.microsoft.com/azure/devops/pipelines/tasks/reference/go-tool-v0) Azure Pipelines build task supports installing the Microsoft build of Go.
For more details, see [the GoTool@0 section of the Migration Guide](eng/doc/MigrationGuide.md#the-gotool0-azure-pipelines-task).

### The `go-install.ps1` script

Expand All @@ -121,6 +121,11 @@ It can install specific versions or the latest releases.

If you use Azure Pipelines, try running the script in a [script step](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/cmd-line-v2?view=azure-pipelines) and pass the `-AzurePipelinePath` argument to automatically set up `go` in the environment for future steps.

### Binary archive

[Signed builds of Go](https://github.com/microsoft/go/blob/microsoft/main/eng/doc/Downloads.md)
for several platforms are available as `zip` and `tar.gz` files.

### Build from source

#### Pre-patched source tarball
Expand Down
35 changes: 25 additions & 10 deletions eng/doc/MigrationGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,6 @@ To comply with Microsoft internal policy for the use of Go, most projects need t

1. [Use the Microsoft build of Go **for CI (Continuous Integration) and build environments.**](#ci-and-build-environment-migration-steps)
- See [Microsoft Toolset Identification](./MicrosoftToolsetIdentification.md) if it's not clear which distribution of Go you're currently using.
1. If you use a version of Go prior to 1.25, [enable `systemcrypto`](#enable-systemcrypto).
- Starting with 1.25 (Linux and Windows) and 1.26 (macOS), `systemcrypto` is enabled by default, and no action is required.
1. [**Test** your program.](#testing)
- It's important to test on all target platforms. The changes to runtime behavior are platform-specific.
1. Consider **whether your project must be FIPS compliant** and if so, [**review your project**](#review-project-for-fips-compliance).
Expand All @@ -31,9 +29,14 @@ Like the official Go distribution, the Microsoft build of Go has no Go runtime c
Your Go application is still a single executable binary.
However, in some cases, it may now have additional dependencies.

Regardless of which method you use to install Go, we recommend picking a specific major version of Go and setting up your build system to use the latest update to that major version, a.k.a. pinning the major version.
Both official Go and the Microsoft build of Go occasionally have breaking changes in new major versions, and pinning lets you plan for and execute migrations at your own pace.
However, we recognize that pinning increases maintenance burden when there are no breaking changes, and ultimately the risk must be evaluated in the context of each project.
> [!TIP]
> Regardless of which method you use to install Go, we recommend picking a specific major version of Go and setting up your build system to use the latest update to that major version.
> (For example, `1.26.*`. This is also called "pinning" to major version `26`.)
> Both official Go and the Microsoft build of Go occasionally have breaking changes in new major versions, and pinning lets you migrate to the next major version at your own pace.
>
> However, pinning increases maintenance burden when there are no breaking changes, because you are responsible for making sure you aren't using a version of Go that is past End-of-Life (EOL) and insecure.
> Some projects may prefer to always use the latest version of Go to be sure they never miss maintenance, even though this puts the project at risk of unexpected breaks when a new major version is released.
> Ultimately, these risks must be evaluated in the context of each project.

## What's different?

Expand All @@ -59,12 +62,24 @@ This section describes some migration scenarios we know about and the path we re
>
> The scenarios in the following sections simply offer targeted guidance to help find the easiest approach.

### The `GoTool@0` Azure Pipelines step
### The `GoTool@0` Azure Pipelines task

The [GoTool@0](https://learn.microsoft.com/azure/devops/pipelines/tasks/reference/go-tool-v0) Azure Pipelines build task supports installing the Microsoft build of Go.

To use it, set these parameters:

The `GoTool@0` step doesn't currently support the Microsoft build of Go, and there is no equivalent step.
(See [microsoft/go#483](https://github.com/microsoft/go/issues/483).)
* `version`: the task supports the version formats `1.X`, `1.X.Y`, and `1.X.Y-Z`, and if there is a partial match, it installs the latest matching version. We recommend using the latest major version, currently `1.26`.
* `goDownloadUrl`: use `https://aka.ms/golang/release/latest` to select the Microsoft build of Go.

The most universal replacement is to use a `script` step to run [the cross-platform `go-install.ps1` script](/README.md#the-go-installps1-script).
The resulting step in a yml-based Azure Pipeline looks like this:

```yml
- task: GoTool@0
displayName: 'Install Go'
inputs:
version: '1.26'
goDownloadUrl: 'https://aka.ms/golang/release/latest'
```

### A `go` toolset that happens to be on my build agent

Expand Down Expand Up @@ -106,7 +121,7 @@ Install instructions [are in the project README file](/README.md#ubuntu).
### A OneBranch Azure Pipeline

We are not aware of an enhanced migration path for OneBranch pipelines that should be preferred over the Azure Pipelines migrations mentioned above.
See the above sections for [`GoTool@0`](#the-gotool0-azure-pipelines-step) and [container jobs](#an-azure-pipelines-container-job-referring-to-the-official-golang-container-image) to find the best fit for your project.
See the above sections for [`GoTool@0`](#the-gotool0-azure-pipelines-task) and [container jobs](#an-azure-pipelines-container-job-referring-to-the-official-golang-container-image) to find the best fit for your project.

### Direct download of the Go `tar.gz` or `zip` file

Expand Down
Loading