Rush configuration

This post outlines the configuration needed to implement rush orchestration for the following purposes:

• Ensuring developers may document changes before submitting a Pull Request
• Incrementing the version number of each Azure template according to the type of change
• Automatically generating change logs based on the descriptions provided by developers

Getting started

ℹ️ If you want to tag along, you will find the repo I'm using in this sample here: Rush-for-IaC-Before.

The initial configuration follows the usual process of setting up a new repo:

• install rush: npm install -g @microsoft/rush
• clone or initialize your repo
• generate rush configuration files; inside your project directory run rush init --overwrite-existing.

npm install -g @microsoft/rush
cd c:\\REPO_ROOT
rush init  --overwrite-existing

You only need --overwrite-existing if you are adding rush to an existing project. It won't override your Bicep templates. See Use "rush init" to initialize your repo for a summary of files that will be created

You will now see a new rush.json file and a common folder in the root directory of your project.

Rush configuration

Using rush in the IaC project will require few extra changes compared to the usual setup of Node projects.

Add package.json files

Add a package.json file to each folder containing Bicep template.

This is because rush operates within the Node.js and JavaScript/TypeScript ecosystem, where package.json files define project metadata, dependencies, etc. Rush is using this files to find projects is managed, and to increase versions.

Define the template name (used later in rush.json) and an initial version number:

AzureTemplates/FunctionApp/package.json

{
    "name": "function-app",
    "version": "0.0.1"
}

AzureTemplates/ApplicationInsights/package.json

{
    "name": "application-insights",
    "version": "0.0.1"
}

Configure rush

I keep my config really simple, focusing on basics: repository URL, email validation and most importantly, the projects references.

Depending on your repo, you may want to update the gitPolicy with a domain of your company. If the repo will be public, consider using your commit email address.

⚠️ Replace the rushVersion, pnpmVersion and nodeSupportedVersionRange with the currently installed versions.

Update the projects element with references to folders that contain your Bicep templates. This part is important, because Rush does not automatically scan for projects using wildcards.

rush.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/rush.schema.json",
  "rushVersion": "5.134.0",
  "pnpmVersion": "9.10.0",
  "nodeSupportedVersionRange": ">=18.20.3 <19.0.0 || >=20.14.0 <21.0.0",
  "projectFolderMaxDepth": 3,
  "gitPolicy": {
    "versionBumpCommitMessage": "chore: Bump versions [skip ci]",
    "changeLogUpdateCommitMessage": "chore: Update changelogs [skip ci]",
    "allowedEmailRegExps": [
      "[^@]+@users\\.noreply\\.github\\.com"
    ],
    "sampleEmail": "example@users.noreply.github.com"
  },
  "repository": {
    "url": "https://github.com/kkazala/Rush-for-IaC-Before.git",
    "defaultBranch": "main",
    "defaultRemote": "origin"
  },

  "projects": [
    {
      "packageName": "function-app",
      "projectFolder": "AzureTemplates/FunctionApp",
      "versionPolicyName": "AzTemplateSpecs"
    },
    {
      "packageName": "application-insights",
      "projectFolder": "AzureTemplates/ApplicationInsights",
      "versionPolicyName": "AzTemplateSpecs"
    }
  ]
}

You will find the default rush.json file here: rush.json.

Configure version policies

In Rush, version policies are a way to define how the versions of different packages in a monorepo should be managed and incremented. These policies help maintain consistency in versioning, automate version bumps, and control how packages are released. They are especially useful when you have many interdependent packages in a monorepo, and you want to establish clear rules for versioning and publishing them.

common\config\rush\version-policies.json

[
  {
    "definitionName": "individualVersion",
    "policyName": "AzTemplateSpecs"
  }
]

Quick test

Typically you would run rush update to install packages required by your projects. We are not building a Node project here, so let's jump right into the test.

Run rush change -v to ensure everything is configured correctly.

rush change -v

Since I'm still in main branch and didn't make any changes to the templates, it returns "No changes were detected to relevant packages on this branch. Nothing to do."

Branch policy

You may use the rush change -v command to ensure that Pull Request is only accepted if change files have been generated. Use it in a pipeline defined in a build validation policy on main branch.

If changes to the code were made but no change files can be found for the project, you will see an error: "ERROR: The following projects have been changed and require change descriptions, but change descriptions were not detected for them: [...]"

Release management

Release managers execute rush version --bump to increase package version based on version policies. The version is saved in the package.json files. At the same time, the change files created by rush change command (common/changes folder) are used to generate/update changelog.js and changelog.md files.

rush version --bump

If needed, release managers may update the changelog.js file and regenerate the changelog.md using rush publish --regenerate-changelogs.

rush publish --regenerate-changelogs

ℹ️ You will find the results of the above changes in the rush branch of the Rush-for-IaC-Before repo.

Next step: Set version numbers in Bicep templates.