Skip to content

Latest commit

 

History

History
81 lines (53 loc) · 5.8 KB

standard-ci-env-variables.md

File metadata and controls

81 lines (53 loc) · 5.8 KB
Raw

Standardized Environment Variables for CI Services

Owner Tomáš Matoušek

The .NET Core SDK is implementing new scenarios that require source control manager information. We want to make it very easy to embed repo-specific information in built assets as a means of creating a strong relationship between binary and source.

To make it possible to provide application platform provided experiences across CI services, we need a standardized set of environment variables that are supported across those same CI services. Ideally, this set of environment variables would be supported across multiple CI services and useful for multiple application environments, not just .NET.

Context

The .NET Core SDK Team is implementing a set of scenarios that establish a strong relationship between binary and source. Some of these scenarios are purely for auditing/pedigree analysis and others are for debugging.

The more simple scenarios simply record source repo information that is readily available into various informational fields in built assets.

Source control information needed:

  • Commit ID/hash
  • Repository URL
  • Source Control Manager name (git, tfvc, etc.)

Places to store this information:

  • AssemblyInformationalVersion attribute.
  • NuGet nuspec file (manifest for NuGet package).

This information doesn't need to be in a specific format, although accurate would be good. It should be descriptive and intuitive per the given source control system so that human readers can work their way back to source (assuming they have access).

The following examples demonstrate how the Roslyn team has implemented this same scenario in their own build. It should be easy for anyone to include the same information in built artifacts.

Example -- Microsoft.CodeAnalysis.CSharp.dll:

[assembly: AssemblyInformationalVersion("2.4.0-beta1-62122-04+ab56a4a6c32268d925014a3e45ddce61fba715cd")]

Example -- Microsoft.Net.Compilers.nupkg (NuGet package):

<repository type="git" url="https://github.com/dotnet/roslyn" commit="ab56a4a6c32268d925014a3e45ddce61fba715cd"/>

Note that the final implementation provided by the .NET Core SDK might look slightly differently from the Roslyn examples, but it will be similar. There will be a separate spec on this feature. This document is focussed on the CI service integration.

Proposed Standard Environment Variables

The .NET Core SDK needs are oriented around source control. As a result, the initial list is source control oriented, but there is no affinity to source control on the general idea of standardized environment variables.

It is important that these environment variables do not conflict with other variables. To avoid that, all environment variables will be prepended with STANDARD_CI_. This name is a first proposal for the idea and it may get changed based on feedback.

  • STANDARD_CI_SOURCE_REVISION_ID -- Commit hash / ID; Example: 2ba93796dcf132de447886d4d634414ee8cb069d
  • STANDARD_CI_REPOSITORY_URL -- URL for repository; Example: https://github.com/dotnet/corefx
  • STANDARD_CI_REPOSITORY_TYPE -- Source control manager name; Example: git, tfvc, mercurial, svn

The following strings are well-known values for STANDARD_CI_REPOSITORY_TYPE. Other values can be used for source control managers not listed in this table.

STANDARD_CI_REPOSITORY_TYPE Source Control Manager
git git
tfvc Team Foundation Version Control
svn Apache Subversion
mercurial Mercurial

Support from CI Services

This plan will only work if CI services decide to support these environment variables. An important question is whether CI services have similar environment variables already. The table below suggests that the information we need is already available. An arbitrary sample of CI services were picked for this exercise.

Environment Variable VSTS Travis CI AppVeyor Circle CI AWS CodeBuild Team City OpenShift
STANDARD_CI_SOURCE_REVISION_ID BUILD_SOURCEVERSION TRAVIS_COMMIT APPVEYOR_REPO_COMMIT CIRCLE_SHA1 CODEBUILD_RESOLVED_SOURCE_VERSION build.vcs.number OPENSHIFT_BUILD_COMMIT
STANDARD_CI_REPOSITORY_URL BUILD_REPOSITORY_URI CIRCLE_REPOSITORY_URL CODEBUILD_SOURCE_REPO_URL vcsroot.url OPENSHIFT_BUILD_SOURCE
STANDARD_CI_REPOSITORY_TYPE APPVEYOR_REPO_SCM

The VSTS team has graciously agreed to publish environment variables in the proposed STANDARD_CI format.