Beachball Documentation

The @microsoft/esrp-npm-release tool is a CLI designed for Microsoft teams to release npm packages to ESRP in dependency-topological order. This ensures that a package's internal dependencies are published before the package itself, preventing dangling references and installation failures in consuming repositories.

How it works

The tool is a bundled CLI (dist/index.mjs) intended to be run during a release job. It does not calculate dependency order itself; instead, it expects a directory of "packed packages" organized into numbered dependency layers. For each layer, the tool:

1. Zips the layer's package tarballs.
2. Uploads the zip to a temporary "staging" Azure Blob Storage account.
3. Calls the ESRP release API to publish the layer and waits for completion.
4. Deletes the staged zip (with an automated lifecycle policy fallback).

When to use this tool

• Use it when: You have a large monorepo or many packages where publishing order is critical to prevent broken dependencies.
• Do NOT use it when: You are managing single packages or small monorepos where the official EsrpRelease task is simpler, or if you prefer manual grouping.

The github-app-token tool allows you to mint GitHub App installation tokens by signing a GitHub App JWT using an Azure Key Vault key. This approach improves security because the GitHub App private key is stored only within Azure Key Vault and is never exposed as a secret in GitHub Actions, Azure Pipelines, or your repository. The tool uses the Azure CLI (az keyvault key sign) to perform the signing operation.

Prerequisites

1. GitHub App: Create a GitHub App and install it on the target repository. Note the Client ID (distinct from the App ID).
2. Private Key: Generate a private key for the app and save it locally.
3. Azure Key Vault: Import the private key into an Azure Key Vault as a key supporting the RS256 sign operation.
4. Authentication: Ensure the environment running the CLI (local machine via az login or Azure Pipelines via AzureCLI@2 task) has permission to perform the sign operation on the Key Vault key.

node github-app-token.mjs create --app-client-id "YOUR_CLIENT_ID" --key-id "https://my-vault.vault.azure.net/keys/my-github-app-key" --repository "owner/repo"

The beachball-change-file skill is designed to guide AI agents through the change file generation process without using the interactive beachball change CLI.

Workflow:

1. The agent uses the skill's instructions to identify which packages have changed.
2. The agent analyzes the diffs for each package.
3. The agent generates a change file manually, assigning the correct type and comment to each package (while respecting configuration settings like disallowedChangeTypes).

Why use the skill instead of the CLI? The beachball change command is limited because it only accepts a single --type and --message. Applying one type to all packages is often inaccurate, and running the command multiple times with --package would result in multiple separate change files instead of a single consolidated one. The skill allows the agent to create a single, high-quality change file containing multiple distinct package entries.

The staging setup uses a storage account with specific configurations for security and automation:

Containers

• staging: Temporarily hosts zipped layers. Blobs are cleaned up by a lifecycle policy after 3 days (or immediately after successful release).
• release-state: Persists retry state so ADO pipeline retries can resume. Blobs are cleaned up after 90 days.

Required RBAC Roles

The User-Assigned Managed Identity must be assigned the following data-plane roles at the storage account scope. Control-plane roles like Contributor are not sufficient:

1. Storage Blob Data Contributor: Allows listing, reading, writing, and deleting blobs in staging and release-state.
2. Storage Blob Delegator: Allows the identity to mint short-lived user-delegation SAS tokens used by ESRP to download artifacts.

Note: RBAC propagation can take several minutes. If you encounter 403 errors immediately after setup, wait a few minutes and retry.

Security Compliance

Storage account keys and public blob access are disabled. Access is managed via Entra ID authentication and short-lived user delegation SAS URLs, complying with Microsoft's Safe Secrets Standard (SFI-ID4.2.1).

Unlike tools that rely on commit messages for versioning, beachball uses change files to manage package versioning and changelog generation.

Change files are .json files located in the /change directory of your repository. They contain metadata about a change, including a description, the change type (e.g., minor), the package name, and the author's email.

Advantages:

• Reviewability: Change files provide clear visual diffs in Pull Requests, allowing reviewers to verify the change type and message easily.
• Flexibility: Authors can modify a change file to correct a change type without needing to amend git history.

In a monorepo, you can enable groupChanges: true in your beachball configuration to consolidate change information for all changed packages on a branch into a single change file.

{
  "comment": "Upgrading React to 16.8.x to use hooks",
  "type": "minor",
  "packageName": "my-amazing-app",
  "email": "me@me.me"
}