Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Makes changes to the “CI Integration” page #659

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 67 additions & 4 deletions docs/concepts/ci-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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:

Expand All @@ -36,16 +36,79 @@ 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 a pre-built task `npmAuthenticate@0` 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.2 Configure Git.**

```yml
- script: |
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'
```

**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: |
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'
- script: |
npm run beachball:publish
displayName: 'Publishing'
```