Unified build access story

[mmitche]

Unified Build Access Story

For .NET 5 and beyond, we need to have a unified build notification story that our customers can rely on. Today, our partners use multiple different mechanisms for build notification: aka.ms links, dotnet-install, etc. Most appear to check the productVersion.txt file for changes. Our goal is to unify on one single mechanism for build notifications: aka.ms links.

While aka.ms links are our best option, they do suffer from some drawbacks:

• They don't work for internal builds today (the aka.ms lins go to non-accessible locations)
• They are updated automatically with new builds, so even if a previous build was validated and called latest, a customer polling the aka.ms link could falsely assume a new build was being run.

To address these drawbacks, we would ideally have the following:

• aka.ms that work for both public and internal builds. Ideally, internal builds would authenticate and redirect authentication to the build uri.
• aka.ms liks that indicate varying levels of quality via their path. For example, we may have the following in the paths of the aka.ms links:
  • daily - every build from the current mainline dev branch (produced by the product repos)
  • signed - latest signed build from a branch (produced by Stage-DotNet)
  • validated - latest build that has been validated (produced by Stage-DotNet)
  • preview - latest preview build that has been signed, validated, and signed off on (produced by Stage-DotNet)
  • ga - latest official release build, updated on release day. Note: GA will not append anything to the aka.ms link. (produced either by Stage-DotNet, or the forth-coming Publishing pipeline)

Today, we generate aka.ms links automatically during publishing of dev builds. In addition to those links that are generated, the release pipeline must generate aka.ms links for the other various phases of the build and release process.

Business Objectives

This epic is complete when:

• [x] There is a consistent method for categorizing builds of varying quality
• [x] There is a consistent mechanism partners can use to access builds of varying quality
• [x] The release pipeline can publish signed, validated, and released builds in a way consistent with daily builds
• [x] Internal builds are accessible by internal partners
• [x] All documentation for servicing is complete
• [x] Usage telemetry is collected

Much of this epic is described in the dotnet-install script use case doc.

Timeline

Deliverable	Date	Notes
Build Categories	2/3	Done
Publishing v3 allows feed overrides	2/26	Done
Staging pipeline publishes signed and validated bits	3/19	Done
Release pipeline publishes ga and preview bits	3/17	Done
aka.ms links for internal builds	2/12	Done
aka.ms links are flattened	2/12	Done
Channels updated	2/9	Done
dotnet-install scripts use aka.ms links		To be completed by the install scripts team. Done
Update aka.ms links in existing docs	3/5	Done
Documentation	3/25	Done
Telemetry	3/29	Done

Stakeholders

• Customers who access builds via dotnet-install scripts
• First-party customers who want access to internal builds of dotnet
• Release team
• Product teams' developers and management
• Engineering services team's developers and management

Risks

• Customers may have specialized mechanisms we don't know about to access builds. Our plan is to change the structure of the links, and we could break those mechanisms if we are not careful.
• aka.ms outages could block accessing builds, leading to additional failures that would need to be investigated
• aka.ms may throttle or have capacity limits that we will need to be aware of
• Authentication story through aka.ms links is unknown
• Low adoption rate due to already existing mechanisms for accessing builds

Dependencies

• Arcade
• Aka.MS
• Stage-DotNet pipeline
• Release pipeline
• Azure DevOps

Serviceability

• Tests (unit, functional) for generating the aka.ms links
• aka.ms link PAT
• May require AAD for accessing internal builds
• Threat model may need to be updated if we add a tool for automatically accessing secrets and appending to the URL.

Rollout and deployment

• The changes that are in arcade will be rolled out via the standard promotion mechanism
• Changes in dotnet-release will be rolled out to production only after a successful test pipeline run
  • Rollouts in dotnet-release are on-demand, no more than once a week
  • Risks are that dotnet-release does not currently run any publishing on test runs, but could be mitigated by publishing to a staging location, or appending test to the aka.ms link to make this possible

Usage Telemetry

• We can collect usage data from the aka.ms links

FR Handoff

• We will write documentation on how the links are generated
• We will create documentation for the Engineering services team to investigate issues in the Stage-DotNet pipeline and how to investigate issues with accessing the builds.
• We will create documentation for the Engineering services team foe investigating aka.ms outages/problems with aka.ms.

[mmitche]

/cc @markwilkie @leecow @shawnro @jcagme

[mmitche]

/cc @adityapatwardhan

[markwilkie]

@jcagme - adding this to the release epic as it doesn't seem this work deserves its own. We'll want to chat more about where it fits priority wise. It would certainly be a good thing to have before .NET5 RTM. So maybe there should be a follow up epic for after this initial work, but before rtm.... Regardless, we can chat more.

[timmydo]

Would be nice to have something here. Also if the tags were in a github repo or something to make them more discoverable.

[michellemcdaniel]

This epic is complete!