Github Workflows

Reusable workflows and actions

Important

Many of these workflows require a Personal Access Token to function.

Create a new PAT with Repo access
- It is recommended that this is a service account user
- Note: This user/bot will need to have access to push to your repo's default branch. This can be configured in the branch protection rules.
Add the PAT as an Actions Organization secret
- Set the Name to SVC_CLI_BOT_GITHUB_TOKEN
- Paste in your new PAT as the Value
- Set Repository Access to 'Selected Repositories'
- Click the gear icon to select repos that need access to the PAT
  - This can be edited later
- Click Add Secret

Opinionated publish process for npm

github is the source of truth for code AND releases. Get the version/tag/release right on github, then publish to npm based on that.

work on a feature branch, commiting with conventional-commits
merge to main
A push to main produces (if your commits have fix: or feat:) a bumped package.json and a tagged github release via githubRelease
A release cause npmPublish to run.

Just need to publish to npm? You could use any public action to do step 4. Use this repo's npmPublish if you need either

codesigning for Salesforce CLIs
integration with CTC or if you own other repos that need those features and just want consistency.

githubRelease

creates a github release based on conventional commit prefixes. Using commits like fix: etc (patch version) and feat: wow (minor version). A commit whose body (not the title) contains BREAKING CHANGES: will cause the action to update the packageVersion to the next major version, produce a changelog, tag and release.

name: create-github-releaseon:
push:
branches: [main]jobs:
release:
uses: salesforcecli/github-workflows/.github/workflows/create-github-release.yml@mainsecrets: inherit# you can also pass in values for the secrets# secrets:# SVC_CLI_BOT_GITHUB_TOKEN: gh_pat00000000

npmPublish

This will verify that the version has not already been published. There are additional params for signing your plugin and integrating with Change Traffic Control (release moratoriums) that you probably only care about if your work for Salesforce.

example usage

on:
release:
# the result of the githubRelease workflowtypes: [published]jobs:
my-publish:
uses: salesforcecli/github-workflows/.github/workflows/npmPublish.ymlwith:
tag: latestgithubTag: ${{ github.event.release.tag_name }}secrets: inherit# you can also pass in values for the secrets# secrets:# NPM_TOKEN: ^&*$

works with npm, too

with:
packageManager: npm

Plugin Signing

Plugins created by Salesforce teams can be signed automatically with sign:true if the repo is in salesforcecli or forcedotcom gitub organization.

You'll need the CLI team to enable your repo for signing. Ask in https://salesforce-internal.slack.com/archives/C0298EE05PU

Plugin signing is not available outside of Salesforce. Your users can add your plugin to their allow list (unsignedPluginAllowList.json)

on:
release:
# the result of the githubRelease workflowtypes: [published]jobs:
my-publish:
uses: salesforcecli/github-workflows/.github/workflows/npmPublish.ymlwith:
sign: truetag: latestgithubTag: ${{ github.event.release.tag_name }}secrets: inherit

Prereleases

main will release to latest. Other branches can create github prereleases and publish to other npm dist tags.

You can create a prerelease one of two ways:

Create a branch with the prerelease/** prefix. Example prerelease/my-fix
1. Once a PR is opened, every commit pushed to this branch will create a prerelease
2. The default prerelease tag will be dev. If another tag is desired, manually set it in your package.json. Example: 1.2.3-beta.0
Manually run the create-github-release workflow in the Actions tab
1. Click Run workflow
  1. Select the branch you want to create a prerelease from
  2. Enter the desired prerelease tag: dev, beta, etc

Note

Since conventional commits are used, there is no need to manually remove the prerelease tag from your package.json. Once the PR is merged into main, conventional commits will bump the version as expected (patch for fix:, minor for feat:, etc)

Setup:

Configure the branch rules for wherever you want to release from
Modify your release and publish workflows like the following

name: create-github-releaseon:
push:
branches:
- main# point at specific branches, or a naming convention via wildcard
- prerelease/**tags-ignore:
- '*'workflow_dispatch:
inputs:
prerelease:
type: stringdescription: 'Name to use for the prerelease: beta, dev, etc. NOTE: If this is already set in the package.json, it does not need to be passed in here.'jobs:
release:
uses: salesforcecli/github-workflows/.github/workflows/create-github-release.yml@mainsecrets: inheritwith:
prerelease: ${{ inputs.prerelease }}# If this is a push event, we want to skip the release if there are no semantic commits# However, if this is a manual release (workflow_dispatch), then we want to disable skip-on-empty# This helps recover from forgetting to add semantic commits ('fix:', 'feat:', etc.)skip-on-empty: ${{ github.event_name == 'push' }}

name: publishon:
release:
# both release and prereleasestypes: [published]# support manual release in case something goes wrong and needs to be repeated or testedworkflow_dispatch:
inputs:
tag:
description: github tag that needs to publishtype: stringrequired: truejobs:
# parses the package.json version and detects prerelease tag (ex: beta from 4.4.4-beta.0)getDistTag:
outputs:
tag: ${{ steps.distTag.outputs.tag }}runs-on: ubuntu-lateststeps:
- uses: actions/checkout@v4with:
ref: ${{ github.event.release.tag_name || inputs.tag }}
- uses: salesforcecli/github-workflows/.github/actions/getPreReleaseTag@mainid: distTagnpm:
uses: salesforcecli/github-workflows/.github/workflows/npmPublish.yml@mainneeds: [getDistTag]with:
tag: ${{ needs.getDistTag.outputs.tag || 'latest' }}githubTag: ${{ github.event.release.tag_name || inputs.tag }}secrets: inherit

Publishing from multiple long-lived branches

In this example main publishes to npm on a 1.x.x version and uses latest. some-other-branch publishes version 2.x.x and uses the v2 dist tag

name: version, tag and github releaseon:
push:
# add the other branch so that it causes github releases just like main doesbranches: [main, some-other-branch]jobs:
release:
uses: salesforcecli/github-workflows/.github/workflows/githubRelease.yml@mainsecrets: inherit

on:
release:
# the result of the githubRelease workflowtypes: [published]jobs:
my-publish:
uses: salesforcecli/github-workflows/.github/workflows/npmPublish.ymlwith:
# ternary-ish https://github.com/actions/runner/issues/409#issuecomment-752775072# if the version is 2.x we release it on the `v2` dist tagtag: ${{ startsWith( github.event.release.tag_name || inputs.tag, '1.') && 'latest' || 'v2'}}githubTag: ${{ github.event.release.tag_name }}secrets: inherit

Opinionated Testing Process

Write unit tests to tests units of code (a function/method).

Write not-unit-tests to tests larger parts of code (a command) against real environments/APIs.

Run the UT first (faster, less expensive for infrastructure/limits).

name: testson:
push:
branches-ignore: [main]workflow_dispatch:
jobs:
unit-tests:
uses: salesforcecli/github-workflows/.github/workflows/unitTest.yml@mainnuts:
needs: unit-testsuses: salesforcecli/github-workflows/.github/workflows/nut.yml@mainsecrets: inheritstrategy:
matrix:
os: [ubuntu-latest, windows-latest]fail-fast: falsewith:
os: ${{ matrix.os }}

Other Tooling

nut conditional on commit message

# conditional nuts based on commit message includes a certain stringsandbox-nuts:
needs: [nuts, unit-tests]if: contains(github.event.push.head_commit.message,'[sb-nuts]')uses: salesforcecli/github-workflows/.github/workflows/nut.yml@mainsecrets: inheritwith:
command: test:nuts:sandboxos: ubuntu-latest

externalNut

Scenario
you have NUTs on a plugin that uses a library
you want to check changes to the library against those NUTs

see https://github.com/forcedotcom/source-deploy-retrieve/blob/> e09d635a7b852196701e71a4b2fba401277da313/.github/workflows/test.yml#L25 for an example

automerge

This example calls the automerge job. It'll merge PRs from dependabot that are
up to date with main
mergeable (per github)
all checks have completed and none failed (skipped may not have run)

name: automergeon:
workflow_dispatch:
schedule:
- cron: '56 2,5,8,11 * * *'jobs:
automerge:
uses: salesforcecli/github-workflows/.github/workflows/automerge.yml@main# secrets are neededsecrets: inherit

need squash?

automerge:
with:
mergeMethod: squash

versionInfo

requires npm to exist. Use in a workflow that has already done that
given an npmTag (ex: 7.100.0 or latest) returns the numeric version (foo => 7.100.0) plus > the xz linux tarball url and the short (7 char) sha.
Intended for releasing CLIs, not for general use on npm packages.

# inside steps
- uses: salesforcecli/github-workflows/.github/actions/versionInfo@mainid: version-infowith:
version: ${{ inputs.version }}npmPackage: sfdx-cli
- run: echo "version is ${{ steps.version-info.outputs.version }}
- run: echo "sha is ${{ steps.version-info.outputs.sha }}
- run: echo "url is ${{ steps.version-info.outputs.url }}

validatePR

Checks that PRs have a link to a github issue OR a GUS WI in the form of @W-12456789@ (the @ are to be compatible with git2gus)

name: pr-validationon:
pull_request:
types: [opened, reopened, edited]# only applies to PRs that want to merge to mainbranches: [main]jobs:
pr-validation:
uses: salesforcecli/github-workflows/.github/workflows/validatePR.yml@main

prNotification

Mainly used to notify Slack when Pull Requests are opened.
For more info see .github/actions/prNotification/README.md

name: Slack Pull Request Notificationon:
pull_request:
types: [opened, reopened]jobs:
build:
runs-on: ubuntu-lateststeps:
- name: Notify Slack on PR openenv:
WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}PULL_REQUEST_AUTHOR_ICON_URL: ${{ github.event.pull_request.user.avatar_url }}PULL_REQUEST_AUTHOR_NAME: ${{ github.event.pull_request.user.login }}PULL_REQUEST_AUTHOR_PROFILE_URL: ${{ github.event.pull_request.user.html_url }}PULL_REQUEST_BASE_BRANCH_NAME: ${{ github.event.pull_request.base.ref }}PULL_REQUEST_COMPARE_BRANCH_NAME: ${{ github.event.pull_request.head.ref }}PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}PULL_REQUEST_REPO: ${{ github.event.pull_request.head.repo.name }}PULL_REQUEST_TITLE: ${{ github.event.pull_request.title }}PULL_REQUEST_URL: ${{ github.event.pull_request.html_url }}uses: salesforcecli/github-workflows/.github/actions/prNotification@main

VS Code Extension Workflows

This repository includes reusable workflows for VS Code extension CI/CD, supporting both monorepo and single-extension repositories.

Prerequisites

Before using these workflows, ensure your repository has:

Required Secrets (configured as GitHub Actions secrets):
- IDEE_GH_TOKEN - Personal Access Token with repo permissions for creating releases and pushing tags
- VSCE_PERSONAL_ACCESS_TOKEN - VS Code Marketplace Personal Access Token (create one)
- IDEE_OVSX_PAT - Open VSX Personal Access Token (create one)
Repository Structure:
- For monorepos: Extensions under a common directory (default: packages/)
- For single repos: Extension at repository root
- Each extension must have a valid package.json with VS Code extension metadata
Optional Local Actions (only for vscode-manual-publish.yml and vscode-promote-stable.yml):
- .github/actions/npm-install-with-retries - Custom npm install with retry logic
- .github/actions/check-ci-status - Validates CI checks passed before publish
- .github/actions/repackage-vsix-stable - Repackages pre-release VSIX as stable
- .github/actions/publish-vsix - Publishes to VS Code Marketplace and/or Open VSX
Note: Most workflows (like vscode-publish-extensions.yml and vscode-promote-prerelease.yml) are fully self-contained and don't require these local actions.

Architecture Overview

The VS Code workflows follow a modular design:

CI/Testing (vscode-ci-template.yml) - Lints, compiles, and tests across multiple OS/Node versions
Packaging (vscode-package.yml) - Creates VSIX files without publishing
Publishing (vscode-publish-extensions.yml) - Complete release pipeline with version bumping and marketplace publishing
Promotion (vscode-promote-prerelease.yml, vscode-promote-stable.yml) - Promotes vetted builds between release channels

Versioning Strategy

These workflows use an odd/even minor version convention to distinguish release types:

Nightly builds: Odd minor versions (e.g., 0.5.x-nightly.20260709)
Pre-release: Odd minor versions (e.g., 0.5.3)
Stable releases: Even minor versions (e.g., 0.6.0)

Benefits:

Clear visual distinction between release channels
Prevents accidental overwrites
Predictable version progression: nightly 0.5.x → pre-release 0.5.y → stable 0.6.0

Version bump types:

major: Breaking change → next major with first odd minor (e.g., 0.5.3 → 1.1.0)
minor: New feature → next odd minor (e.g., 0.5.3 → 0.7.0)
patch: Bug fix → increment patch, maintain odd minor (e.g., 0.5.3 → 0.5.4)
auto: Analyzes conventional commits to determine bump type

Common Inputs

Most workflows share these common inputs:

node-version (optional) - Node.js version to use (default: 22.x)
extensions-root (optional) - Root directory for extensions (default: packages)
dry-run (optional) - Run without publishing/tagging (default: false)
pre-release (optional) - Mark as pre-release version (default: true)
registries (optional) - Where to publish: all, vsce, or ovsx (default: all)
package-manager (optional) - npm, pnpm, or yarn (default: npm)
package-manager-version (optional) - pnpm version to install
cache-dependency-path (optional) - Package-manager lockfile path (default: package-lock.json)
install-command (optional) - Dependency installation command (default: npm ci)
package-command / prerelease-package-command (optional) - Commands that create stable and prerelease VSIX artifacts
artifact-glob (optional) - Glob for the produced VSIX artifacts (default: packages/**/*.vsix)
publish-web-vsix (optional) - Publish a web-target VSIX to the CBWeb internal marketplace (default: false)

Node Lifecycle Contract

The workflows execute Node-module lifecycle activities; they do not require a specific package.json script name. New consumers should expose the conventional scripts below, while existing consumers can map their current scripts or direct commands through workflow inputs.

Activity	Recommended script	Workflow input
Install dependencies	manager-native frozen or immutable install	`install-command`
Lint	`lint`	`lint-command`
Build	`build`	`build-command`
Test	`test`	`test-command`
CI test variant	`test:ci`	`test-command`
Coverage	`test:coverage`	`coverage-command`
Merge coverage	`test:coverage:report`	`coverage-report-command`
Additional quality checks	`test:quality`	`quality-command`
Package stable artifact	`package`	`package-command`
Package prerelease artifact	`package:prerelease`	`prerelease-package-command`

The existing npm defaults remain compatible with VSE: npm run compile, npm run package:packages, and npm run package:packages:prerelease. Direct commands are valid when a repository does not use scripts, such as cd lana && pnpm exec vsce package --no-dependencies.

vscode-release-explicit

Builds and publishes VS Code extensions from explicitly declared extension paths.

Usage:

name: Nightly Releaseon:
schedule:
- cron: '0 4 * * *'workflow_dispatch:
jobs:
nightly:
uses: salesforcecli/github-workflows/.github/workflows/vscode-release-explicit.yml@mainwith:
extensions: '["packages/ext1", "packages/ext2"]'# JSON array of pathsregistries: all # all | marketplace | openvsxpre-release: trueversion-bump: auto # auto | major | minor | patchpackage-command: 'npx vsce package --no-dependencies'dry-run: falsesecrets:
VSCE_PAT: ${{ secrets.VSCE_PAT }}OVSX_PAT: ${{ secrets.OVSX_PAT }}

Inputs:

extensions (required) - JSON array of extension directory paths
registries (optional) - Where to publish: all, marketplace, or openvsx (default: all)
pre-release (optional) - Mark as pre-release version (default: true)
version-bump (optional) - Version bump strategy: auto, major, minor, or patch (default: auto)
package-command (optional) - Command to build VSIX packages (default: vsce package)
bundle-command (optional) - Command to bundle extension code (default: npm run vscode:bundle)
dry-run (optional) - Skip actual publishing for testing (default: false)

Required Secrets:

VSCE_PAT - VS Code Marketplace Personal Access Token
OVSX_PAT - Open VSX Personal Access Token

vscode-package

Packages VS Code extensions into VSIX files without publishing.

Usage:

jobs:
package:
uses: salesforcecli/github-workflows/.github/workflows/vscode-package.yml@mainwith:
branch: mainartifact-name: vsix-packagespre-release: truedry-run: false

vscode-ci-template

Reusable CI workflow template for VS Code extension repositories. Runs tests across multiple OS and Node.js versions with coverage reporting.

Usage:

jobs:
ci:
uses: salesforcecli/github-workflows/.github/workflows/vscode-ci-template.yml@mainwith:
package-manager: npminstall-command: npm cilint-command: 'npm run lint'build-command: 'npm run build'test-command: 'npm run test'coverage-command: 'npm run test:coverage'coverage-report-command: 'npm run test:coverage:report'quality-command: 'npm run test:quality'package-command: 'npm run package'prerelease-package-command: 'npm run package:prerelease'

vscode-publish-extensions

Full-featured publish workflow with automatic version bumping, GitHub releases, and marketplace publishing. Supports auto-detecting changed extensions or publishing specific extensions.

Usage:

jobs:
publish:
uses: salesforcecli/github-workflows/.github/workflows/vscode-publish-extensions.yml@mainwith:
branch: mainextensions: changed # or 'all' or 'ext1,ext2'registries: all # all | vsce | ovsxpre-release: trueversion-bump: auto # auto | major | minor | patchextensions-root: packages # for monoreposexclude-web-vsix: 'false'publish-web-vsix: false # set true only for repos with a CBWeb web VSIXslack-notification-title: '🎉 Extensions Released Successfully!'node-version: '22.x'dry-run: falsesecrets: inherit

pnpm caller example:

jobs:
publish:
uses: salesforcecli/github-workflows/.github/workflows/vscode-publish-extensions.yml@mainwith:
branch: mainextensions: lanaextensions-root: .package-manager: pnpmpackage-manager-version: '10'cache-dependency-path: pnpm-lock.yamlinstall-command: pnpm run ci:installpackage-command: cd lana && pnpm exec vsce package --no-dependenciesprerelease-package-command: cd lana && pnpm exec vsce package --pre-release --no-dependenciesartifact-glob: lana/*.vsixdry-run: truesecrets: inherit

Yarn caller example:

jobs:
publish:
uses: salesforcecli/github-workflows/.github/workflows/vscode-publish-extensions.yml@mainwith:
package-manager: yarncache-dependency-path: yarn.lockinstall-command: yarn install --network-timeout 600000package-command: yarn package:packagesprerelease-package-command: yarn package:packages:prereleasesecrets: inherit

Key Features:

Auto-detects changed extensions in monorepos
Smart version bumping using odd/even convention
Conventional commit analysis
Creates GitHub releases with VSIX artifacts
Publishes to VS Code Marketplace and/or Open VSX
Slack notifications on success

Inputs:

extensions (optional) - Extensions to release: changed, all, or comma-separated names (default: changed)
version-bump (optional) - Version bump type: auto, patch, minor, major (default: auto)
slack-notification-title (optional) - Slack notification title (default: 🎉 Extensions Released Successfully!)

vscode-publish-release-vsix

Downloads every VSIX asset from a GitHub release in the calling repository and publishes it to the VS Code Marketplace. VSIX files are found recursively, the release's pre-release state is preserved, and already-published versions are skipped.

jobs:
publish:
uses: salesforcecli/github-workflows/.github/workflows/vscode-publish-release-vsix.yml@mainwith:
release-tag: v67.10.0dry-run: true # Download and inspect without publishingsecrets: inherit

openvsx-publish-release-vsix

Downloads every VSIX asset from a GitHub release in the calling repository and publishes it to Open VSX. VSIX files are found recursively, the release's pre-release state is preserved, and already-published versions are skipped.

jobs:
publish:
uses: salesforcecli/github-workflows/.github/workflows/openvsx-publish-release-vsix.yml@mainwith:
release-tag: v67.10.0dry-run: true # Download and inspect without publishingsecrets: inherit

vscode-promote-prerelease

Promotes a vetted nightly build to pre-release on VS Code Marketplace and Open VSX. This workflow finds the oldest unpromoted nightly that meets the minimum age requirement, verifies CI checks passed, and publishes it as a pre-release.

Usage:

jobs:
promote:
uses: salesforcecli/github-workflows/.github/workflows/vscode-promote-prerelease.yml@mainwith:
extension-name: 'my-extension'# Used for tracking tagsmin-tag-age-days: '7'# Nightly must be at least 7 days oldvsix-name-pattern: 'my-extension-*.vsix'# Pattern to match VSIX filesexclude-web-vsix: 'true'# Exclude *-web-* VSIX filesdry-run: 'false'secrets: inherit

Requirements:

Nightly tags matching v{version}-nightly.* pattern (e.g., v1.2.3-nightly.20260709)
GitHub releases for each nightly tag with VSIX files attached
Passing CI checks on nightly commits

How it works:

Finds oldest nightly tag ≥ min-tag-age-days that hasn't been promoted
Verifies CI checks passed for that commit
Downloads VSIX from nightly GitHub release
Publishes to marketplace(s) as pre-release
Creates marketplace-prerelease-{extension-name}-v{version} tracking tag

vscode-promote-stable

Promotes a vetted pre-release to stable. This workflow finds the latest pre-release, verifies quality gates, repackages the VSIX for stable, and publishes it.

Usage:

jobs:
promote:
uses: salesforcecli/github-workflows/.github/workflows/vscode-promote-stable.yml@mainwith:
extension-name: 'my-extension'vsix-name-pattern: 'my-extension-*.vsix'exclude-web-vsix: 'true'extensions-root: 'packages'dry-run: 'false'secrets: inherit

Requirements:

marketplace-prerelease-* tracking tags from previous promotions
Local actions in calling repository (see Prerequisites section above)

Note: This workflow requires local actions. For a fully self-contained alternative, use vscode-promote-prerelease.yml.

vscode-manual-publish

Manually publish a specific nightly or CI build to the marketplace. Supports two source paths:

Tag path: Publish from a nightly GitHub Release
Run path: Publish from a CI build artifact (with quality check bypass)

Usage:

jobs:
manual-publish:
uses: salesforcecli/github-workflows/.github/workflows/vscode-manual-publish.yml@mainwith:
extension-name: 'my-extension'vsix-name-pattern: 'my-extension-*.vsix'version-tag: 'v0.5.3-nightly.20260301'# OR use source-run-idslot: 'pre-release'# or 'stable'registries: 'all'exclude-web-vsix: 'true'extensions-root: 'packages'dry-run: 'false'secrets: inherit

Requirements:

Local actions in calling repository (see Prerequisites section above)
Environment: manual-publish-gate (with required reviewers for approval)

Note: This workflow requires local actions. Use for special cases where you need to manually control which build gets published.

Name		Name	Last commit message	Last commit date
Latest commit History 730 Commits
.cursor/rules		.cursor/rules
.git2gus		.git2gus
.github		.github
images		images
.gitignore		.gitignore
CODEOWNERS		CODEOWNERS
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE.txt		LICENSE.txt
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Uh oh!

Repository files navigation

Github Workflows

Opinionated publish process for npm

githubRelease

npmPublish

Plugin Signing

Prereleases

Publishing from multiple long-lived branches

Opinionated Testing Process

Other Tooling

nut conditional on commit message

externalNut

automerge

versionInfo

validatePR

prNotification

VS Code Extension Workflows

Prerequisites

Architecture Overview

Versioning Strategy

Common Inputs

Node Lifecycle Contract

vscode-release-explicit

vscode-package

vscode-ci-template

vscode-publish-extensions

vscode-publish-release-vsix

openvsx-publish-release-vsix

vscode-promote-prerelease

vscode-promote-stable

vscode-manual-publish

About

Releases

Packages

Used by

Contributors

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Github Workflows

Opinionated publish process for npm

githubRelease

npmPublish

Plugin Signing

Prereleases

Publishing from multiple long-lived branches

Opinionated Testing Process

Other Tooling

nut conditional on commit message

externalNut

automerge

versionInfo

validatePR

prNotification

VS Code Extension Workflows

Prerequisites

Architecture Overview

Versioning Strategy

Common Inputs

Node Lifecycle Contract

vscode-release-explicit

vscode-package

vscode-ci-template

vscode-publish-extensions

vscode-publish-release-vsix

openvsx-publish-release-vsix

vscode-promote-prerelease

vscode-promote-stable

vscode-manual-publish

About

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors