Skip to content

Release Process

Jump to bottom
Tsuyoshi Ushio edited this page Aug 7, 2026 · 2 revisions

Release Process

This page describes how to release @azure/functions-skills to npm and create the corresponding GitHub release.

Release pipelines

The pipelines are in the azure-functions-skills Azure DevOps folder.

Pipeline Purpose
Pre-release Builds a package from the selected mirror branch. It can validate the package without publishing, or publish it with an npm prerelease tag such as preview.
Official Runs the official tests and creates the immutable drop artifact used for a production release.
Release Validates or publishes the drop from one explicitly selected Official run. Production publishing uses ESRP Release.

Pre-release is independent of Official. You do not need a completed Official run to build, validate, or publish a preview package. Release, however, must consume a successful Official run.

Prerequisites

The release operator must have permission to:

  • Queue the Pre-release, Official, and Release pipelines.
  • Select a pipeline resource run when queuing Release.
  • Approve the Azure DevOps manual validation used by ESRP publishing.
  • Push signed tags to Azure/azure-functions-skills.
  • Review and publish GitHub releases.

The Azure DevOps Variable Group azure-functions-skills-release must be authorized for the three release pipelines. Do not enable open access. It contains:

Variable Purpose Secret
ApplicationInsightsConnectionString Injects the release telemetry configuration into the package. Use the complete Application Insights connection string. Yes
EsrpOwners Comma-separated Microsoft UPNs responsible for the release. Use individual users, not a distribution list or security group. Recommended
EsrpApprovers Comma-separated Microsoft UPNs for ESRP metadata. These must be individual users and different from the owners. Recommended
EsrpManualApprovers Azure DevOps users or groups allowed to approve the manual validation step. No

The Variable Group's inherited Library security normally does not need to be changed. Variable Group security and Pipeline permissions are separate; authorize only the pipelines that need the group.

ESRP infrastructure settings, including the service connection, managed identity, Key Vault, and request-signing certificate, are maintained by the private engineering templates. Do not copy those values into this public repository or this wiki.

1. Prepare the version

Create and merge a PR that updates package.json and package-lock.json to the version being released. Follow Semantic Versioning.

Examples:

  • Preview: 0.1.0-preview.1
  • Production: 0.1.0

Regenerate the plugin payload after changing the version:

npm version <version> --no-git-tag-version
npm run build:plugin-payload
npm run check

Do not create the Git tag yet. The signed tag is created only after npm publishing succeeds.

Wait for the public main commit to be mirrored to the internal Azure DevOps repository. Confirm that the mirror commit SHA matches the public GitHub commit that should be released.

2. Validate the package with Pre-release

Queue Pre-release against the intended mirror branch with:

Parameter Value
Tag preview
Dry Run true

The pipeline builds the package, injects the release telemetry configuration, creates the drop artifact, and runs an unauthenticated npm dry run. It does not publish to npm.

Download the .tgz from the drop artifact and test it in an isolated directory:

mkdir functions-skills-package-test
cd functions-skills-package-test
npm init -y
npm install <path-to-functions-skills.tgz>
npx azure-functions-skills --version
npx azure-functions-skills --help

Test any changed CLI, setup, plugin, skill, or agent behavior before continuing. The package no longer creates .azure-functions-skills/state.local.json; its absence is expected.

3. Optionally publish a preview

To publish the tested prerelease version to npm, queue Pre-release again against the same mirror commit with:

Parameter Value
Tag preview
Dry Run false

Before approving the manual validation, verify:

  • The source commit is the intended commit.
  • The package version is a prerelease version.
  • The npm tag is preview, not latest.
  • The drop artifact is from the current run.

Approve the manual validation. The shared engineering template then publishes through ESRP Release.

Verify the result:

npm view @azure/functions-skills@<version> version
npm view @azure/functions-skills dist-tags
npx --yes @azure/functions-skills@preview --version

Publishing a preview does not require an Official build and does not create a GitHub release.

4. Create the Official artifact

After the final version PR is merged and mirrored, queue Official for the mirrored main branch.

For a production release, set IsPrerelease to false.

Record all of the following from the successful run:

  • Official run number.
  • Build.SourceVersion commit SHA.
  • Package version in the drop artifact.

Download and inspect the .tgz if needed. This Official run is the artifact source for both Release dry-run validation and the real ESRP publication.

5. Validate the Official artifact with Release

Queue Release.

In Resources, select officialBuild, then explicitly choose the successful Official run recorded in the previous step. Do not rely on the automatically selected latest run.

Use:

Parameter Value
Tag latest
Dry Run true

Confirm that the Release run downloads the expected Official drop and that npm dry-run validation succeeds. No package is published in this run.

6. Publish the Official artifact through ESRP

Queue Release again and select the exact same officialBuild run in Resources.

Use:

Parameter Value
Tag latest
Dry Run false

Before approving the manual validation, compare the selected Official run number, commit SHA, package version, and npm tag with the values recorded above.

Approve the manual validation. The Release pipeline delegates to the pinned engineering release template, which publishes the selected .tgz through ESRP Release. Azure DevOps does not need npm credentials or GitHub credentials.

Verify npm:

npm view @azure/functions-skills@<version> version
npm view @azure/functions-skills dist-tags
npx --yes @azure/functions-skills@<version> --version

Confirm that latest points to the new production version and that preview, if present, has not been changed unexpectedly.

7. Create the signed Git tag

Create the tag from the exact public GitHub commit corresponding to the published Official artifact:

git switch main
git pull --ff-only origin main
git rev-parse HEAD
git tag -s v<version> -m "v<version>"
git push origin v<version>

Compare the git rev-parse HEAD value with the Official run's Build.SourceVersion before pushing.

Pushing a v* tag triggers .github/workflows/draft-release.yml. The workflow uses the repository GITHUB_TOKEN to create a draft GitHub release with generated notes. Azure DevOps does not create GitHub tags or releases and does not store a GitHub PAT.

The code-mirror pipeline also mirrors v* tags to the internal Azure DevOps repository. Confirm that the internal tag resolves to the same commit as the public tag.

8. Publish the GitHub release

Open the draft in GitHub Releases.

Review the generated notes, add any required upgrade guidance or breaking-change details, and confirm that the release targets v<version>. Publish the draft after npm and tag verification are complete.

Troubleshooting

Variable Group not found or unauthorized

Confirm that azure-functions-skills-release exists in the internal project and that the specific pipeline is authorized under the Variable Group's Pipeline permissions. Do not enable open access.

Telemetry injection fails

Confirm that the Variable Group contains ApplicationInsightsConnectionString, not the obsolete ApplicationInsightsInstrumentationKey, and that the value is the complete connection string.

Manual validation has no valid approver

Check EsrpManualApprovers. It must contain an Azure DevOps-recognized user or group with permission to approve the validation.

ESRP preflight fails

Check that EsrpOwners and EsrpApprovers contain valid, comma-separated individual Microsoft UPNs and that the owner and approver sets are different. ESRP infrastructure and certificate failures should be handled in the private engineering repository; do not expose those values in public issues.

Release selected the wrong Official run

Cancel the Release run before approval. Queue a new run and explicitly select the correct officialBuild resource. Never publish an artifact whose Official run, commit SHA, and package version have not been verified.

npm version already exists

npm package versions are immutable. Do not retry with different contents under the same version. Prepare a new version, rebuild it through Official, and select the new Official run in Release.

GitHub draft release was not created

Confirm that the public tag starts with v, that the tag push completed, and that the Draft Release GitHub Actions workflow succeeded. If a release already exists for the tag, the workflow intentionally does not overwrite it.

Mirror reports that the tag already exists

Compare the public and internal tag commit SHAs. If they match, no correction is needed. If they differ, stop the release and resolve the mirror inconsistency before proceeding.

Clone this wiki locally