From 0a8f7fe59d790c9d55b1ce591f1ef9e6843ee0e0 Mon Sep 17 00:00:00 2001 From: Ria Carmin Date: Fri, 13 May 2022 19:01:26 -0700 Subject: [PATCH 1/2] Adds an Azure DevOps example --- docs/concepts/ci-integration.md | 97 +++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 4 deletions(-) diff --git a/docs/concepts/ci-integration.md b/docs/concepts/ci-integration.md index 4319d9608..f1784565c 100644 --- a/docs/concepts/ci-integration.md +++ b/docs/concepts/ci-integration.md @@ -8,7 +8,7 @@ category: doc For the repository and package owners who want to automate the bumping of versions based on change files with `beachball`, you'll need to provide some information for your Continuous Integration (CI) systems. These one-time setup steps will be unique for different CI system naturally, but the general idea remain the same. `beachball publish` needs write access to with are the git repo and npm registry. -### Git Authentication +## Git Authentication There are several ways to authenticate against a git repository. Here's one way to do so with a personal token. Put this in your publishing build scripts: @@ -22,7 +22,7 @@ git remote set-url origin https://$(user):$(pat)@github.com/someuser/someproject These commands will give the git user a name and email. Also, the last command will set a different URL for the git remote named "origin". If you have SSH key pairs setup, you would not need to run that last line in your scripts. -### NPM Authentication +## NPM Authentication To publish to a npm registry, you'll need to have access to the write-enabled access token. npm registry has [documentation](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) on how to create automation tokens. Pass this token into the command line: @@ -36,16 +36,105 @@ A common requirement is to be able to publish to a private registry other than n beachball publish -n SOME_AUTH_TOKEN -r http://SOME_REGISTRY_URL/ ``` -### package.json script +## package.json script It's recommended to encapsulate any custom options in a `package.json` script: +> Note: When running Beachball in CI, add the `-y` flag (or `--yes`). That skips the intractive prompts that are commonly unavailable in CI consoles. + ```json { "scripts": { - "publish:beachball": "beachball publish -n $(npm.token)" + "publish:beachball": "beachball publish -y -n $(npm.token)" } } ``` Then inside the CI script, simply call `yarn publish:beachball` or `npm run publish:beachball`. + + +## Examples + +### With Azure DevOps + +**1 Npm authentication**. Azure DevOps has `npmAuthenticate@0` available to create a temporary npm auth token for publishing. + +```yml + - task: npmAuthenticate@0 + inputs: + workingFile: .npmrc +``` + +**2 Git authentication**. + +**2.1 Add env variables.** First, you need to add environment variables. One way to do it is through a _Variable group_. Find it in Library → “+ Variable group” → “+ Add”. + +Add 4 env vars: +- git.pat +- git.user +- git.name +- git.email + +Give your pipeline permissins to access these variables in _Pipeline permissions_. + +**2.1 Configure Git.** You can set up your Azure DevOps pipeline to add git credentials with Git CLI or you can extrapolate it in a Node script like this: + +```js +const shell = require('shelljs'); +const { logger } = require('just-scripts'); + +shell.set('-e'); + +module.exports = function gitAuth() { + logger.info('Authenticating Git'); + shell.exec(`git config user.email "${process.env.GIT_EMAIL}"`); + shell.exec(`git config user.name "${process.env.GIT_NAME}"`); + shell.exec( + `git remote set-url origin https://${process.env.GIT_USER}:${process.env.GIT_PAT}@github.com/someuser/someproject.git`, + ); +}; +``` + +**2.2 Add Npm script.** Add your script to `package.json`, e.g. `"git-auth": "node ./scripts/git-auth.js"`. + +**2.3 Add task.** Add a task to configure Git. + +```yml + - script: | + npm run git-auth + displayName: 'Configure git' + env: + GIT_PAT: $(git.pat) + GIT_USER: $(git.user) + GIT_NAME: $(git.name) + GIT_EMAIL: $(git.email) +``` + +**3 Add publish script** Final step is adding a publish script to `package.json` like e.g. `"beachball:publish": "beachball publish --yes"`. Note, that `npmAuthenticate@0` task is taking care of publishing access, so you do not need to pass an Npm token here. + +Add a task to run the script in the pipeline. + +```yml + - script: | + npm run beachball:publish + displayName: 'Publishing' +``` + +**4 Final configuration** + +```yml + - task: npmAuthenticate@0 + inputs: + workingFile: .npmrc + - script: | + npm run git-auth + displayName: 'Configure git' + env: + GIT_PAT: $(git.pat) + GIT_USER: $(git.user) + GIT_NAME: $(git.name) + GIT_EMAIL: $(git.email) + - script: | + npm run beachball:publish + displayName: 'Publishing' +``` From a162be642453739f7af4344db95e3ac37602cee0 Mon Sep 17 00:00:00 2001 From: Ria Carmin Date: Fri, 13 May 2022 19:56:13 -0700 Subject: [PATCH 2/2] Makes edits --- docs/concepts/ci-integration.md | 46 +++++++-------------------------- 1 file changed, 10 insertions(+), 36 deletions(-) diff --git a/docs/concepts/ci-integration.md b/docs/concepts/ci-integration.md index f1784565c..feebef6e8 100644 --- a/docs/concepts/ci-integration.md +++ b/docs/concepts/ci-integration.md @@ -57,7 +57,7 @@ Then inside the CI script, simply call `yarn publish:beachball` or `npm run publ ### With Azure DevOps -**1 Npm authentication**. Azure DevOps has `npmAuthenticate@0` available to create a temporary npm auth token for publishing. +**1 Npm authentication**. Azure DevOps has a pre-built task `npmAuthenticate@0` to create a temporary npm auth token for publishing. ```yml - task: npmAuthenticate@0 @@ -77,40 +77,17 @@ Add 4 env vars: Give your pipeline permissins to access these variables in _Pipeline permissions_. -**2.1 Configure Git.** You can set up your Azure DevOps pipeline to add git credentials with Git CLI or you can extrapolate it in a Node script like this: - -```js -const shell = require('shelljs'); -const { logger } = require('just-scripts'); - -shell.set('-e'); - -module.exports = function gitAuth() { - logger.info('Authenticating Git'); - shell.exec(`git config user.email "${process.env.GIT_EMAIL}"`); - shell.exec(`git config user.name "${process.env.GIT_NAME}"`); - shell.exec( - `git remote set-url origin https://${process.env.GIT_USER}:${process.env.GIT_PAT}@github.com/someuser/someproject.git`, - ); -}; -``` - -**2.2 Add Npm script.** Add your script to `package.json`, e.g. `"git-auth": "node ./scripts/git-auth.js"`. - -**2.3 Add task.** Add a task to configure Git. +**2.2 Configure Git.** ```yml - script: | - npm run git-auth + git config user.email $(git.email) + git config user.name $(git.name) + git remote set-url origin https://$(git.user):$(git.pat)@github.com/someuser/someproject.git displayName: 'Configure git' - env: - GIT_PAT: $(git.pat) - GIT_USER: $(git.user) - GIT_NAME: $(git.name) - GIT_EMAIL: $(git.email) ``` -**3 Add publish script** Final step is adding a publish script to `package.json` like e.g. `"beachball:publish": "beachball publish --yes"`. Note, that `npmAuthenticate@0` task is taking care of publishing access, so you do not need to pass an Npm token here. +**3 Add publish script.** Final step is adding a publish script to `package.json` like e.g. `"beachball:publish": "beachball publish --yes"`. Note, that `npmAuthenticate@0` task is taking care of publishing access, so you do not need to pass an Npm token here. Add a task to run the script in the pipeline. @@ -120,20 +97,17 @@ Add a task to run the script in the pipeline. displayName: 'Publishing' ``` -**4 Final configuration** +**4 Final configuration.** ```yml - task: npmAuthenticate@0 inputs: workingFile: .npmrc - script: | - npm run git-auth + git config user.email $(git.email) + git config user.name $(git.name) + git remote set-url origin https://$(git.user):$(git.pat)@github.com/someuser/someproject.git displayName: 'Configure git' - env: - GIT_PAT: $(git.pat) - GIT_USER: $(git.user) - GIT_NAME: $(git.name) - GIT_EMAIL: $(git.email) - script: | npm run beachball:publish displayName: 'Publishing'