As release-it is increasingly used from CI/CD environments such as Travis, Circle CI or GitHub Actions, this page outlines some popular ways to configure this. Do you have additional successful integrations, or experiencing issues with the existing ones below, feel free to open a ticket.
In order to push the release commit and tag back to the remote, the CI/CD environment should be authenticated with the original host (e.g. GitHub). Also see Git.
When using an SSH
url (such as [email protected]:user/repo.git
), add the public key to the CI/CD environment.
When using an HTTPS
url (such as https://github.com/user/project.git
), things are slightly more complicated. For
GitHub, add the GITHUB_TOKEN
token to the CI/CD environment. Then make sure to add this token as a password in the
origin url before running release-it. An example is this .travis.yml
section:
script:
- git remote rm origin
- git remote add origin https://[user]:${GITHUB_TOKEN}@github.com/[user]/[project].git
- git symbolic-ref HEAD refs/heads/main
Replace [user]
and [project]
with the actual values.
To run release-it from a GitHub Action, here's an example job (fragment) to configure a Git user (to push the release
commit), and expose NPM_TOKEN
for publishing to the npm registry and GITHUB_TOKEN
for the GitHub Release:
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 0
- name: git config
run: |
git config user.name "${GITHUB_ACTOR}"
git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
- run: npm install
- run: npm run release
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
The fetch-depth: 0
option is only necessary when the Git history is required e.g. if using a plugin such as
@release-it/conventional-changelog.
If you enjoy watching a video, David from Kodaps created a great walk-through including setting up npm and GitHub tokens: How to use GitHub Actions & Release-It to Easily Release Your Code
To publish a package to the (or any) npm registry from within a CI or CD environment such as Travis or Circle, make the
NPM_TOKEN
available in the .npmrc
file. This file should look like this before release-it attempts to publish the
package:
//registry.npmjs.org/:_authToken=$NPM_TOKEN
One way to achieve this is to set the NPM_TOKEN
in the CI environment, and from a script do:
npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
This will create/update the .npmrc
file and add the token there. Ideally you should either .gitignore
this file,
otherwise you might end up committing it to your repo if you are using release-it's git
options.
Since release-it executes npm whoami
as a prerequisite check, which does not seem to respect the .npmrc
file,
the --npm.skipChecks
argument can be used.
Here's an example fragment of what to add to .travis.yml
:
deploy:
script:
- echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc
- npm run release
In short, here's the relevant fragment from .circleci/config.yml
:
jobs:
deploy:
steps:
- attach_workspace:
at: ~/repo
- run:
name: Authenticate with registry
command: npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
During the release process, your project's package.json
will be updated to bump the version. You will need to setup
CircleCI with a non read-only SSH key pair from your Github account if you want it to be able to push that change back
to the repo.
See Publishing npm Packages Using CircleCI for more details.
Make sure the GITHUB_TOKEN
or GITLAB_TOKEN
environment variable is set in the CI/CD environment to publish (or
draft) GitHub or GitLab releases. This works the same as on your local machine.
When using release-it with GitLab CI and SSH, make sure the following requirements are met:
git
andssh
as packages are installed in the jobnpm install
is run beforehand- Environment variables contain
GITLAB_TOKEN
,SSH_PRIVATE_KEY
,CI_EMAIL
andCI_USER
- A user with permissions to write to protected branches or deploy key (env var) is added to the repo
The following example shows a pipeline that first installs Git and OpenSSH to Alpine, adds the SSH private key to the SSH agent, configures SSH, and eventually executes release-it:
before_script:
- apk add --no-cache git openssh
- eval `ssh-agent -s`
- echo "${SSH_PRIVATE_KEY}" | tr -d '\r' | ssh-add - > /dev/null # add ssh key
- mkdir -p ~/.ssh
- chmod 700 ~/.ssh
- '[[ -f /.dockerenv ]] && echo -e "Host *\n\tStrictHostKeyChecking no\n\n" > ~/.ssh/config'
- git checkout $CI_COMMIT_REF_NAME
- git remote set-url origin "[email protected]:$CI_PROJECT_PATH.git"
- git config --global user.name "${CI_USERNAME}"
- git config --global user.email "${CI_EMAIL}"
- npm install
script:
- npx release-it --ci
Note: the git remote set-url
could also be set with the git.pushRepo
option in the release-it configuration.
Some people have reported an issue when using GitLab CI (in #573):
ERROR fatal: tag vX.X.X already exists
Here is an example script sequence for GitLab to mitigate the issue:
- git pull origin $CI_COMMIT_REF_NAME
- npm run release
Specifically, make sure to fetch
with the --prune-tags
argument before release-it tries to create the Git tag:
{
"hooks": {
"before:init": "git fetch --prune --prune-tags origin"
}
}