primer/publish
This GitHub Action publishes to npm with the following conventions:
- If we're on the
master
branch, theversion
field is used as-is and we just runnpm publish --access public
.- After publishing a new version on the
master
branch, we tag the commit SHA withv{version}
via the GitHub API. - If the version in
package.json
is already published, we exit with a0
code. Previously, we exited with a78
code, which was Actions v1-speak for "neutral", but this has been removed from Actions v2.
- After publishing a new version on the
- If we're on a
release-<version>
branch, we publish a release candidate to thenext
npm dist-tag with the version in the form:<version>-rc.<sha>
.- A status check is created with the context
npm version
noting whether theversion
field inpackage.json
matches the<version>
portion of the branch. If it doesn't, the check's status is marked as pending.
- A status check is created with the context
- Otherwise, we publish a "canary" release, which has a version in the form:
0.0.0-<sha>
.
Status checks
Depending on the branch, a series of statuses will be created by this action in your checks: publish is the action's check, and publish {package-name} is a commit status created by the action that reports the version published and links to unpkg.com
via "Details":
If you're on a release branch (release-<version>
) and the <version>
portion of the branch name doesn't match the version
field in package.json
, you'll get a pending status reminding you to update it:
Usage
You will need to provide an npm access token with publish permissions via the NPM_AUTH_TOKEN
secret in the Actions visual editor if you haven't already. The GITHUB_TOKEN
secret is also required to create tags after releasing on the master branch.
We suggest that you place this action after any linting and/or testing actions to catch as many errors as possible before publishing.
Actions v2
To use this in an Actions v2 workflow, add the following YAML to one or more of your steps:
- uses: primer/publish@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
You can pass additional options via the args
key:
- uses: primer/publish@master
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
+ args: '--dry-run -- --unsafe-perm'
Actions v1
To use this in an Actions v1 workflow, add the following snippet to .github/main.workflow
:
action "publish" {
uses = "primer/publish@master"
secrets = [
"GITHUB_TOKEN",
"NPM_AUTH_TOKEN",
]
}
Options
--dry-run
Default: false
Does everything publish would do except actually publishing to the registry. Reports the details of what would have been published.
Example
action "publish" {
uses = "primer/publish@master"
secrets = ["GITHUB_TOKEN", "NPM_AUTH_TOKEN"]
args = "--dry-run"
}
--dir=<path>
Default: .
Accepts a path to the directory that contains the package.json
to publish.
Example
action "publish" {
uses = "primer/publish@master"
secrets = ["GITHUB_TOKEN", "NPM_AUTH_TOKEN"]
args = "--dir=packages/example"
}
npm CLI arguments
It's possible to pass additional arguments to npm
via the args
field in your workflow action. Because the primer-publish
CLI accepts options of its own (such as --dry-run
), you need to prefix any npm
arguments with --
:
action "publish" {
uses = "primer/publish@master"
+ args = ["--", "--registry=https://registry.your.org"]