@orderly.network/release-tag

Shared Orderly release tag CLI for creating dev, qa, and prod deployment tags.

Install

npm install -D @orderly.network/release-tag

Usage

orderly-release-tag --env dev
orderly-release-tag --env qa
orderly-release-tag --env prod

Use --config to load project-specific tag rules:

orderly-release-tag --env qa --config ./release-tag.config.mjs

Use --dry-run to validate the release path without creating a tag or triggering GitLab:

orderly-release-tag --env dev --dry-run

--dry-run still performs validation, but it does not create a local tag, push a tag, or trigger a GitLab pipeline.

Modes

RELEASE_TAG_MODE supports:

• auto: use trigger mode when trigger configuration and token are available; otherwise use local tag mode.
• trigger: require GitLab trigger configuration and trigger the release pipeline.
• local: create and push the Git tag from the local machine.

The CLI loads .env.local from the current working directory when present. Existing shell environment variables take precedence over .env.local values.

Trigger mode

Trigger mode creates a GitLab trigger pipeline instead of pushing the tag from your local machine.

RELEASE_TAG_MODE=trigger \
GITLAB_TRIGGER_TOKEN=<gitlab_pipeline_trigger_token> \
orderly-release-tag --env dev --project-id 52443474

GITLAB_TRIGGER_TOKEN must be a GitLab Pipeline Trigger Token. Do not use CI_JOB_TOKEN.

The project id can also be provided through GitLab's predefined CI_PROJECT_ID:

RELEASE_TAG_MODE=trigger \
CI_PROJECT_ID=52443474 \
GITLAB_TRIGGER_TOKEN=<gitlab_pipeline_trigger_token> \
orderly-release-tag --env dev

RELEASE_TAG_BRANCH is optional for dev and qa. When omitted, the current branch is used. By default, prod triggers main; this can be changed with prodEnv / prodBranch. --config is passed to the triggered pipeline as RELEASE_TAG_CONFIG. In trigger mode, the config path must be relative to the repository so the remote pipeline can load the same file.

Local mode

Local mode creates and pushes the Git tag from the current machine.

RELEASE_TAG_MODE=local orderly-release-tag --env dev

Before creating a tag, the CLI validates that:

• the current checkout is on a branch, not detached HEAD;
• the prod environment releases from the configured prod branch;
• local HEAD matches origin/<current-branch>;
• a base release tag can be resolved from the latest tag matching the configured release tag rule.

Configuration

The CLI uses the built-in strategy by default. To customize tag rules, add release-tag.config.mjs in the current working directory, or pass a config path with --config / RELEASE_TAG_CONFIG.

export default {
  environments: ["dev", "qa", "prod"],
  prodEnv: "prod",
  prodBranch: "main",

  releaseTagRule: {
    pattern: /^sdk-v(\d+)\.(\d+)\.(\d+)$/,
    description: "sdk-vX.Y.Z",
    example: "sdk-v1.0.0",
    format({ major, minor, patch }) {
      return `sdk-v${major}.${minor}.${patch}`;
    },
  },

  formatPrereleaseTag({ releaseTag, branchPart, env, nextNumber }) {
    return branchPart
      ? `${releaseTag}-${branchPart}-${env}-${nextNumber}`
      : `${releaseTag}-${env}-${nextNumber}`;
  },
};

releaseTagRule.pattern must use its first three capture groups for major, minor, and patch. formatPrereleaseTag must append nextNumber as the final tag suffix so the CLI can find and increment existing prerelease tags.

Tag format

The next tag is based on the latest release tag matching releaseTagRule.

Examples:

• main + dev: v1.0.0-dev-0
• feature/order-entry + qa: v1.0.0-order-entry-qa-0
• main + prod: v1.0.1

If a matching prerelease tag already exists, the numeric suffix is incremented.

Environment variables

| Name | Description | | ---------------------- | --------------------------------------------------------------------------------------------- | | RELEASE_TAG_MODE | auto, trigger, or local. Defaults to auto. | | RELEASE_TAG_ENV | Optional release environment. --env takes precedence. | | RELEASE_TAG_CONFIG | Optional path to release-tag.config.mjs. --config takes precedence. | | RELEASE_TAG_BRANCH | Optional branch override for dev and qa trigger pipelines. Must match the current branch. | | CI_PROJECT_ID | Optional GitLab project id used by trigger mode. --project-id takes precedence. | | GITLAB_TRIGGER_TOKEN | GitLab Pipeline Trigger Token used by trigger mode. |

Troubleshooting

No release tag found. Expected at least one tag like v1.0.0.

Create or fetch a base release tag first. The CLI only increments tags that match the configured releaseTagRule; the built-in rule matches vX.Y.Z.

Local HEAD does not match origin/<branch>.

Push or pull the current branch before running the release command again.

RELEASE_TAG_MODE=trigger requires trigger project id and GITLAB_TRIGGER_TOKEN.