plugin-release-management

Plugin designed to handle all tasks related to signing, releasing, and testing npm packages.

Releases

The following steps are automated for package releases

Version Bump | Prerelease | ChangeLog

This plugin will not bump your package version for you. Use https://github.com/salesforcecli/github-workflows?tab=readme-ov-file#githubrelease and conventional commit tags to manage that.

It used to.

Build

After determining the next version, the plugin builds the package using yarn build. This means that you must have a build script included in the package.json

Signing

If you pass the --sign (-s) flag into the release command, then the plugin will sign the package and verify that the signature exists in S3.

Publishing

Once the package has been built and signed it will be published to npm. The command will not exit until the new version is found on the npm registry.

Install

sfdx plugins:install release-management@x.y.z

Issues

Please report any issues at https://github.com/forcedotcom/cli/issues

Contributing

1. Please read our Code of Conduct
2. Create a new issue before starting your project so that we can keep track of what you are trying to add/fix. That way, we can also offer suggestions or let you know if there is already an effort in progress.
3. Fork this repository.
4. Build the plugin locally
5. Create a topic branch in your fork. Note, this step is recommended but technically not required if contributing using a fork.
6. Edit the code in your fork.
7. Write appropriate tests for your changes. Try to achieve at least 95% code coverage on any new code. No pull request will be accepted without unit tests.
8. Sign CLA (see CLA below).
9. Send us a pull request when you are done. We'll review your code, suggest any needed changes, and merge it in.

CLA

External contributors will be required to sign a Contributor's License Agreement. You can do so by going to https://cla.salesforce.com/sign-cla.

Build

To build the plugin locally, make sure to have yarn installed and run the following commands:

# Clone the repository
git clone git@github.com:salesforcecli/plugin-release-management

# Install the dependencies and compile
yarn install
yarn build

To use your plugin, run using the local ./bin/dev or ./bin/dev.cmd file.

# Run using local run file.
./bin/dev npm

There should be no differences when running via the Salesforce CLI or using the local run file. However, it can be useful to link the plugin to do some additional testing or run your commands from anywhere on your machine.

# Link your plugin to the sfdx cli
sfdx plugins:link .
# To verify
sfdx plugins

Commands

• sfdx channel promote
• sfdx cli artifacts compare
• sfdx cli install jit test
• sfdx cli install test
• sfdx cli release automerge
• sfdx cli release build
• sfdx cli releasenotes
• sfdx cli tarballs prepare
• sfdx cli tarballs smoke
• sfdx cli tarballs verify
• sfdx cli versions inspect
• sfdx dependabot automerge
• sfdx github check closed
• sfdx npm dependencies pin
• sfdx npm package release
• sfdx plugins trust verify
• sfdx repositories

sfdx channel promote

promote a s3 channel

USAGE
  $ sfdx channel promote -t  -c sf|sfdx [--json] [--flags-dir ] [-d] [-C ] [-p win|macos|deb]
    [-s ] [-m ] [-i] [-x] [-T linux-x64|linux-arm|win32-x64|win32-x86|darwin-x64] [-v ]

FLAGS
  -C, --promote-from-channel=     the channel name that you want to promote
  -T, --architecture-target=<option>...  comma-separated targets to promote (e.g.: linux-arm,win32-x64)
                                         
  -c, --cli=<option>                     (required) the cli name to promote
                                         
  -d, --dryrun                           If true, only show what would happen
  -i, --[no-]indexes                     append the promoted urls into the index files
  -m, --max-age=                  [default: 300] cache control max-age in seconds
  -p, --platform=<option>...             the platform to promote
                                         
  -s, --sha=                      the short sha to promote
  -t, --promote-to-channel=       (required) [default: stable] the channel name that you are promoting to
  -v, --version=                  the version of the candidate to be promoted, which must exist already in s3.
                                         Used to fetch the correct sha
  -x, --[no-]xz                          also upload xz

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  promote a s3 channel

  promote a s3 channel

EXAMPLES
  $ sfdx channel promote --candidate latest-rc --target latest --platform win --platform mac

See code: src/commands/channel/promote.ts

sfdx cli artifacts compare

Look for breaking changes in artifacts (schemas and snapshots) from plugins. Must be run in CLI directory.

USAGE
  $ sfdx cli artifacts compare [--json] [--flags-dir ] [-p ] [-r ] [-c ]

FLAGS
  -c, --current=    Current CLI version to compare against. Defaults to the version on the CLI in the current
                           directory.
  -p, --plugin=...  List of plugins to check for breaking changes.
  -r, --previous=   Previous CLI version to compare against. Defaults to the last published version.

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

EXAMPLES
  $ sfdx cli artifacts compare

See code: src/commands/cli/artifacts/compare.ts

sfdx cli install jit test

Test that all JIT plugins can be successfully installed.

USAGE
  $ sfdx cli install jit test [--json] [--flags-dir ] [-j ]

FLAGS
  -j, --jit-plugin=...  JIT plugin(s) to test, example: @salesforce/plugin-community

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

EXAMPLES
  $ sfdx cli install jit test

See code: src/commands/cli/install/jit/test.ts

sfdx cli install test

install sf or sfdx

USAGE
  $ sfdx cli install test -c sf|sfdx -m installer|npm|tarball [--json] [--flags-dir ] [--channel
    legacy|stable|stable-rc|latest|latest-rc] [--output-file ]

FLAGS
  -c, --cli=<option>         (required) the cli to install
                             
  -m, --method=<option>      (required) the installation method to use
                             
      --channel=<option>     [default: stable] the channel to install from
                             
      --output-file=  [default: test-results.json] the file to write the JSON results to (must be .json)

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  install sf or sfdx

  install sf or sfdx

EXAMPLES
  $ sfdx cli install test --cli sfdx --method installer

  $ sfdx cli install test --cli sfdx --method npm

  $ sfdx cli install test --cli sfdx --method tarball

  $ sfdx cli install test --cli sf --method tarball

  $ sfdx cli install test --cli sf --method tarball --channel stable-rc

See code: src/commands/cli/install/test.ts

sfdx cli release automerge

Attempt to automerge nightly PR

USAGE
  $ sfdx cli release automerge (--owner  --repo ) --pull-number  [--json] [--flags-dir ] [-d]
    [--verbose]

FLAGS
  -d, --dry-run              Run all checks, but do not merge PR
      --owner=        (required) Github owner (org), example: salesforcecli
      --pull-number=  (required) Github pull request number to merge
      --repo=         (required) Github repo, example: sfdx-cli
      --verbose              Show additional debug output

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Attempt to automerge nightly PR

  Attempt to automerge nightly PR

EXAMPLES
  $ sfdx cli release automerge --owner salesforcecli --repo sfdx-cli --pul-number 1049

See code: src/commands/cli/release/automerge.ts

sfdx cli release build

builds a new release from a designated starting point and optionally creates PR in Github

USAGE
  $ sfdx cli release build -c  [--json] [--flags-dir ] [-d ] [-g ] [--build-only]
    [--resolutions] [--only ] [--pinned-deps] [--jit] [--label ] [--patch] [--empty] [--pr-base-branch
    ]

FLAGS
  -c, --release-channel=          (required) the channel intended for this release, examples: nightly, latest-rc,
                                         latest, dev, beta, etc...
  -d, --start-from-npm-dist-tag=  the npm dist-tag to start the release from, examples: nightly, latest-rc
  -g, --start-from-github-ref=    a Github ref to start the release from, examples: main, 7.144.0, f476e8e
      --build-only                       only build the release, do not git add/commit/push
      --empty                            create an empty release PR for pushing changes to later (version will still be
                                         bumped)
      --[no-]jit                         bump the versions of the packages listed in the jitPlugins (just-in-time)
                                         section
      --label=...                 add one or more labels to the Github PR
      --only=...                  only bump the version of the packages passed in, uses latest if version is not
                                         provided
      --patch                            bump the release as a patch of an existing version, not a new minor version
      --[no-]pinned-deps                 bump the versions of the packages listed in the pinnedDependencies section
      --pr-base-branch=           base branch to create the PR against; if not specified, the build determines
                                         the branch for you
      --[no-]resolutions                 bump the versions of packages listed in the resolutions section

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  builds a new release from a designated starting point and optionally creates PR in Github

  builds a new release from a designated starting point and optionally creates PR in Github

ALIASES
  $ sfdx cli latestrc build

EXAMPLES
  $ sfdx cli release build

  $ sfdx cli release build --patch

  $ sfdx cli release build --start-from-npm-dist-tag latest-rc --patch

  $ sfdx cli release build --start-from-github-ref 7.144.0

  $ sfdx cli release build --start-from-github-ref main

  $ sfdx cli release build --start-from-github-ref f476e8e

  $ sfdx cli release build --start-from-github-ref main --prerelease beta

  $ sfdx cli release build --build-only

  $ sfdx cli release build --only @salesforce/plugin-source,@salesforce/plugin-info@1.2.3

See code: src/commands/cli/release/build.ts

sfdx cli releasenotes

pull all relevant information for writing release notes.

USAGE
  $ sfdx cli releasenotes -c sf|sfdx [--json] [--flags-dir ] [-s ] [-m]

FLAGS
  -c, --cli=<option>   (required) the cli to pull information for
                       
  -m, --markdown       format the output in markdown
  -s, --since=  the version number of the previous release. Defaults to the latest-rc version on npm

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  pull all relevant information for writing release notes.
  Requires the GH_TOKEN to be set in the environment.

  pull all relevant information for writing release notes.
  Requires the GH_TOKEN to be set in the environment.

EXAMPLES
  $ sfdx cli releasenotes --cli sf

  $ sfdx cli releasenotes --cli sfdx

  $ sfdx cli releasenotes --cli sf --since 1.0.0

  $ sfdx cli releasenotes --cli sfdx --since 7.19.0

  $ sfdx cli releasenotes --cli sf &gt; changes.txt

  $ sfdx cli releasenotes --cli sf --markdown &gt; changes.md

See code: src/commands/cli/releasenotes.ts

sfdx cli tarballs prepare

remove unnecessary files from node_modules

USAGE
  $ sfdx cli tarballs prepare [--json] [--flags-dir ] [-d] [-t] [--verbose]

FLAGS
  -d, --dryrun   only show what would be removed from node_modules
  -t, --types    remove all types (.d.ts) files from node_modules
      --verbose  show all files paths being removed

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  remove unnecessary files from node_modules

  remove unnecessary files from node_modules

EXAMPLES
  $ sfdx cli tarballs prepare

See code: src/commands/cli/tarballs/prepare.ts

sfdx cli tarballs smoke

smoke tests for the sf CLI

USAGE
  $ sfdx cli tarballs smoke [--json] [--flags-dir ] [--verbose]

FLAGS
  --verbose  show the --help output for each command

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  smoke tests for the sf CLI
  Tests that the CLI and every command can be initialized.

  smoke tests for the sf CLI
  Tests that the CLI and every command can be initialized.

EXAMPLES
  $ sfdx cli tarballs smoke

  $ sfdx cli tarballs smoke

See code: src/commands/cli/tarballs/smoke.ts

sfdx cli tarballs verify

verify that tarballs are ready to be uploaded

USAGE
  $ sfdx cli tarballs verify [--json] [--flags-dir ] [-c sf|sfdx] [-w ]

FLAGS
  -c, --cli=<option>                     [default: sfdx] the cli to verify
                                         
  -w, --windows-username-buffer=  [default: 41] the number of characters to allow for windows usernames

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  verify that tarballs are ready to be uploaded

  verify that tarballs are ready to be uploaded

EXAMPLES
  $ sfdx cli tarballs verify

  $ sfdx cli tarballs verify --cli sfdx

  $ sfdx cli tarballs verify --cli sf

See code: src/commands/cli/tarballs/verify.ts

sfdx cli versions inspect

inspect the CLI version across all install paths

USAGE
  $ sfdx cli versions inspect -c legacy|stable|stable-rc|latest|latest-rc|nightly -l archive|npm --cli sf|sfdx [--json]
    [--flags-dir ] [-d ] [-s]

FLAGS
  -c, --channels=<option>...     (required) the channel you want to inspect (for achives, latest and latest-rc are
                                 translated to stable and stable-rc. And vice-versa for npm)
                                 
  -d, --dependencies=...  glob pattern of dependencies you want to see the version of
  -l, --locations=<option>...    (required) the location you want to inspect
                                 
  -s, --salesforce               show versions of salesforce owned dependencies
      --cli=<option>             (required) [default: sfdx] the CLI you want to inspect
                                 

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  inspect the CLI version across all install paths

  inspect the CLI version across all install paths

EXAMPLES
  $ sfdx cli versions inspect -l archive -c stable

  $ sfdx cli versions inspect -l archive -c stable-rc

  $ sfdx cli versions inspect -l archive npm -c stable

  $ sfdx cli versions inspect -l archive npm -c latest

  $ sfdx cli versions inspect -l archive npm -c latest latest-rc

  $ sfdx cli versions inspect -l archive npm -c stable stable-rc

  $ sfdx cli versions inspect -l npm -c latest --salesforce

  $ sfdx cli versions inspect -l npm -c latest -d @salesforce/core

  $ sfdx cli versions inspect -l npm -c latest -d @salesforce/\*\*/ salesforce-alm

  $ sfdx cli versions inspect -l npm -c latest -d chalk -s

See code: src/commands/cli/versions/inspect.ts

sfdx dependabot automerge

automatically merge one green, mergeable PR up to the specified maximum bump type

USAGE
  $ sfdx dependabot automerge -m major|minor|patch [--json] [--flags-dir ] [-o  -r ] [-d] [-s]
    [--merge-method merge|squash|rebase]

FLAGS
  -d, --dryrun                     only show what would happen if you consolidated dependabot PRs
  -m, --max-version-bump=<option>  (required) [default: minor] the maximum version bump you want to be included
                                   
  -o, --owner=              the organization that the repository belongs to. This defaults to the owner specified
                                   in the package.json
  -r, --repo=               the repository you want to consolidate PRs on. This defaults to the repository
                                   specified in the package.json
  -s, --skip-ci                    add [skip ci] to the merge commit title
      --merge-method=<option>      [default: merge] merge method to use
                                   

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  automatically merge one green, mergeable PR up to the specified maximum bump type

  automatically merge one green, mergeable PR up to the specified maximum bump type

EXAMPLES
  $ sfdx dependabot automerge --max-version-bump patch

  $ sfdx dependabot automerge --max-version-bump minor

  $ sfdx dependabot automerge --max-version-bump major

See code: src/commands/dependabot/automerge.ts

sfdx github check closed

Show open Github issues with GUS WI

USAGE
  $ sfdx github check closed -o  --github-token  [--json] [--flags-dir ]

FLAGS
  -o, --gus=           (required) Username/alias of your GUS org connection
      --github-token=  (required) Github token--store this in the environment as GITHUB_TOKEN

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Show open Github issues with GUS WI

  Description of a command.

EXAMPLES
  $ sfdx github check closed -o me@gus.com

See code: src/commands/github/check/closed.ts

sfdx npm dependencies pin

lock a list of dependencies to a target tag or default to 'latest', place these entries in 'pinnedDependencies' entry in the package.json

USAGE
  $ sfdx npm dependencies pin [--json] [--flags-dir ] [-d] [-t ]

FLAGS
  -d, --dryrun       If true, will not make any changes to the package.json
  -t, --tag=  [default: latest] The name of the tag you want, e.g. 'latest-rc', or 'latest'

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  lock a list of dependencies to a target tag or default to 'latest', place these entries in 'pinnedDependencies' entry
  in the package.json

  lock a list of dependencies to a target tag or default to 'latest', place these entries in 'pinnedDependencies' entry
  in the package.json

See code: src/commands/npm/dependencies/pin.ts

sfdx npm package release

publish npm package

USAGE
  $ sfdx npm package release [--json] [--flags-dir ] [-d] [-s] [-t ] [-a ] [--install] [--prerelease
    ] [--verify] [--githubtag ]

FLAGS
  -a, --npmaccess=   [default: public] access level to use when publishing to npm
  -d, --dryrun              If true, will not commit changes to repo or push any tags
  -s, --sign                If true, then the package will be signed and the signature will be uploaded to S3
  -t, --npmtag=      [default: latest] tag to use when publishing to npm
      --githubtag=   given a github tag, release the version specified in the package.json as is. Useful when
                            you've already done a release and only need npm publish features
      --[no-]install        run yarn install and build on repository
      --prerelease=  determine the next version as -.0 if version is not manually set
      --[no-]verify         verify npm registry has new version after publish and digital signature

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  publish npm package

  publish npm package

See code: src/commands/npm/package/release.ts

sfdx plugins trust verify

Validate a digital signature.

USAGE
  $ sfdx plugins trust verify -n  [--json] [--flags-dir ] [-r ]

FLAGS
  -n, --npm=       (required) Specify the npm name. This can include a tag/version.
  -r, --registry=  The registry name. The behavior is the same as npm.

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  Validate a digital signature.

  Verifies the digital signature on an npm package matches the signature and key stored at the expected URLs.

EXAMPLES
  $ sfdx plugins trust verify --npm @scope/npmName --registry https://npm.pkg.github.com

  $ sfdx plugins trust verify --npm @scope/npmName

See code: @salesforce/plugin-trust

sfdx repositories

list repositories owned and supported by Salesforce CLI

USAGE
  $ sfdx repositories [--json] [--flags-dir ] [--columns  | -x] [--filter ] [--no-header |
    [--csv | --no-truncate]] [--output csv|json|yaml |  | ] [--sort ]

FLAGS
  -x, --extended         show extra columns
      --columns=  only show provided columns (comma-separated)
      --csv              output is csv format [alias: --output=csv]
      --filter=   filter property by partial string matching, ex: name=foo
      --no-header        hide table header from output
      --no-truncate      do not truncate output to fit screen
      --output=<option>  output in a more machine friendly format
                         
      --sort=     property to sort by (prepend '-' for descending)

GLOBAL FLAGS
  --flags-dir=  Import flag values from a directory.
  --json               Format output as json.

DESCRIPTION
  list repositories owned and supported by Salesforce CLI
  For more information on the list of repositories, visit https://github.com/salesforcecli/status.

  list repositories owned and supported by Salesforce CLI
  For more information on the list of repositories, visit https://github.com/salesforcecli/status.

EXAMPLES
  $ sfdx repositories --columns=url --filter='Name=sfdx-core' --no-header | xargs open

  $ sfdx repositories --json | jq -r '.result[] | select(.name=="sfdx-core") | .packages[] | .url

See code: src/commands/repositories/index.ts