Skip to content

How to release a package version

Create a new 2GP package version, confirm it installs, and tag the release. The flags of all three commands are in packaging command flags.

Prerequisites

  • A Dev Hub authenticated locally (sf org login web --set-default-dev-hub) or in CI via npm run ci:auth:devhub — package version creation always targets a Dev Hub.
  • The package already declared in sfdx-project.json under packageDirectories, with either "default": true set on it or its alias known ahead of time (you pass it explicitly or via PACKAGE_ALIAS).
  • In CI, package:version:create pushes its bump commit back to the branch: the git bot secret BASE64_BOT_PRIVATE_KEY set as a repository variable, and npm run ci:auth:gitbot run earlier in the same pipeline step. See how to wire a repository into CI for where that secret is configured.

Create the version

npm run package:version:create -- --package-alias <alias> --package-version 1.5.5.1 --target-dev-hub <devhub>

Always pass --package-version in a pipeline step — the command prompts for it otherwise. The bump commit to sfdx-project.json carries [skip ci].

Validate the install

npm run install:latest:version -- --package <alias> --target-org <org> --installation-key <key>

A version that fails to install here is not release-ready, regardless of how the creation step went.

Tag the release

npm run ci:tag:version -- --package <alias>

Re-running after a partial failure is safe — an existing tag is logged and skipped.

Wire it into the pipeline

None of this is wired into bitbucket-pipelines.yml by default. Add a custom pipeline for it, following the shape of the existing custom pipelines:

custom:
    Release Package Version:
        - variables:
              - name: PackageVersion
        - step:
              name: Create and Tag Package Version
              caches:
                  - npm
              script:
                  - npx -y npm@11.19.0 ci --prefer-offline --no-audit --ignore-scripts
                  - npm run ci:auth:devhub
                  - npm run ci:auth:gitbot
                  - npm run package:version:create -- --package-alias <alias> --package-version $PackageVersion
                  - npm run install:latest:version -- --package <alias> --target-org <org>
                  - npm run ci:tag:version -- --package <alias>

The variables block with no default forces the operator triggering the run to supply PackageVersion — it is not hardcoded. ci:auth:gitbot must run before package:version:create so the push-back has a git identity and an SSH key to push with.

The toolchain stops at creating, installing and tagging: there is no sf package version promote support and no dependency orchestration across packages — promote by hand when a version needs it.