You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
inspect the effective beachball configuration for the repo or a specific package
40
-
41
-
## Options
42
-
43
-
Some of the most common options are summarized below. **For all options, see the pages for [CLI options](https://microsoft.github.io/beachball/cli/options.html) and [config file options](https://microsoft.github.io/beachball/overview/configuration.html).**
44
-
45
-
### `--config`, `-c`
46
-
47
-
Explicit configuration file to use instead of the configuration automatically detected by cosmicconfig.
48
-
49
-
### `--registry`, `-r` (config: `registry`)
50
-
51
-
registry, defaults to https://registry.npmjs.org
52
-
53
-
### `--tag`, `-t` (config: `tag`)
54
-
55
-
- for the `publish` command: dist-tag for npm publishes
56
-
- for the `sync` command: will use specified tag to set the version
57
-
58
-
### `--branch`, `-b` (config: `branch`)
59
-
60
-
target branch from remote (default: as configured in `git config init.defaultBranch`)
61
-
62
-
### `--message`, `-m`
63
-
64
-
- for the `publish` command: message for the checkin (default: "applying package updates")
65
-
- for the `change` command: change file comment for all changed packages
66
-
67
-
### `--type`
68
-
69
-
for the `change` command: [change type](https://microsoft.github.io/beachball/concepts/change-types.html) for all changed packages
70
-
71
-
### `--package`
72
-
73
-
for the `change` command: specific package(s) to create a change file for
In large monorepos, the process of fetching versions for sync or before publishing can be time-consuming due to the high number of packages. To optimize performance, you can override the concurrency for fetching from the registry by setting `options.npmReadConcurrency` (default: 5). You can also increase concurrency for hook calls and publish operations via `options.concurrency` (default: 1; respects topological order).
112
-
113
-
### API surface
114
-
115
-
Beachball **does not** have a public API beyond the provided [options](https://microsoft.github.io/beachball/overview/configuration.html). Usage of private APIs is not supported and may break at any time.
116
-
117
-
If you need to customize something beyond what's currently supported in the options, please open a feature request or talk with the maintainers.
118
-
119
-
### AI integration
120
-
121
-
Normally, Beachball uses an interactive CLI prompt for generating change files. Since this doesn't work for AI agents, we provide a **change file skill** that guides AI agents through creating properly formatted change files. See the [AI integration](https://microsoft.github.io/beachball/concepts/ai-integration) docs for setup instructions.
3
+
the sunniest version bumping tool - see [`packages/beachball`](./packages/beachball) for details
|`--prerelease-prefix`||| prerelease prefix (e.g. `beta`) for packages that will receive a prerelease bump |
23
+
|`--publish`, `--no-publish`||`true` (`--publish`) | whether to publish to the npm registry |
24
+
|`--push`, `--no-push`||`true` (`--push`) | whether to commit changes and push them back to the git remote |
25
+
|`--registry`|`-r`|`'https://registry.npmjs.org'`| npm registry for publishing |
26
+
|`--retries`||`3`| number of retries for a package publish before failing |
27
+
|`--tag`|`-t`|`'latest'`| dist-tag for npm publishes |
28
+
|`--token`|`-n`|| credential to use with npm commands (type is specified by `--auth-type`) - locally, use `npm login` instead, or see [alternatives for CI](../concepts/ci-integration)|
29
+
|`--verbose`||`false`| prints additional information to the console |
30
+
|`--yes`|`-y`| if CI detected, `true`| skips the prompts for publish |
Copy file name to clipboardExpand all lines: docs/concepts/ci-integration.md
+37-42Lines changed: 37 additions & 42 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,23 +15,25 @@ To automate the bumping of package versions based on change files, you'll need t
15
15
16
16
## Authentication
17
17
18
-
Automated publishing from a GitHub repo to the public npm registry (`registry.npmjs.org`) typically uses personal access tokens for authentication. These tokens are stored as secrets in your CI system. You should ensure that these secrets are only available to release builds.
18
+
Automated publishing from a GitHub repo to the public npm registry (`registry.npmjs.org`) typically uses personal access tokens (and/or trusted publishing) for authentication. These tokens are stored as secrets in your CI system. You should ensure that these secrets are only available to release builds.
19
19
20
20
For Azure DevOps repos publishing to a private registry, there are other possible approaches (such as using a service account with credentials stored in a key vault) which are not currently covered by these docs.
21
21
22
22
### Generating tokens
23
23
24
24
#### npm token
25
25
26
-
If publishing to the public npm registry (`registry.npmjs.org`), [create a granular access token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website) with write access to **only** the relevant package(s) and/or scope(s). Classic automation tokens are not recommended due to their overly broad permissions.
26
+
If publishing to the public npm registry (`registry.npmjs.org`) from a platform that supports [trusted publishing](https://docs.npmjs.com/trusted-publishers), such as GitHub Actions, you should use trusted publishing instead of a token.
27
27
28
-
#### GitHub token
28
+
Azure DevOps unfortunately doesn't support trusted publishing, so there it's still necessary to [create a granular access token](https://docs.npmjs.com/creating-and-viewing-access-tokens#creating-granular-access-tokens-on-the-website) with write access to **only** the relevant package(s) and/or scope(s).
29
29
30
-
Since a repo's `main`/`master` branch should be protected, this creates some difficulties for pushing changes back during automated publishing.
30
+
#### GitHub token
31
31
32
-
The main way to allow `beachball` to push back to a repo with branch protections is by using a [**fine-grained** personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) with write permissions for **only** the specific repo. (If the repo is in an org that doesn't allow persistent admin access, see [these instructions](https://github.com/microsoft/beachball/issues/1008).)
32
+
Since a repo's `main`/`master`branch should be protected, this creates some difficulties for pushing changes back during automated publishing. There are a few options:
33
33
34
-
An alternative approach is creating a fine-grained PAT with a "machine user" account. Create a new account with an alternate email or [subaddress](https://en.wikipedia.org/wiki/Email_address#Subaddressing) (`+` address), give it contributor permissions to only this repo, and add it under "Restrict who can push to matching branches" in the branch protection rule.
34
+
- Traditional approach: use a [**fine-grained** personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) (PAT) with write permissions for **only** the specific repo. (If the repo is in an org that doesn't allow persistent admin access, see [these instructions](https://github.com/microsoft/beachball/issues/1008).)
35
+
- Variant: create a fine-grained PAT with a "machine user" account. Create a new account with an alternate email or [subaddress](https://en.wikipedia.org/wiki/Email_address#Subaddressing) (`+` address), give it contributor permissions to only this repo, and add it under "Restrict who can push to matching branches" in the branch protection rule.
36
+
- Alternative if publishing via GitHub Actions: use [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token) to generate short-lived tokens. For this purpose, an "app" is essentially just an identity with permissions; you don't need to define any logic or endpoints. Create a GitHub app, install it in your repo, give it permission to bypass policies, and pass its ID and key to the action.
35
37
36
38
(Note that the [built-in `GITHUB_TOKEN`](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) won't work for publishing because that actor can't be given permission to bypass policies.)
37
39
@@ -57,7 +59,7 @@ There are a couple of options here:
57
59
58
60
If you're passing any custom options besides the npm token to `beachball publish`, it's recommended to set them in either the `beachball` config (if they don't interfere with other commands), or a `package.json` script (if specific to `publish`).
59
61
60
-
For example, the following script could be used for publishing public scoped packages:
62
+
For example, the following script could be used for publishing public scoped packages (`access` is also safe to set in the beachball config):
61
63
62
64
```json
63
65
{
@@ -87,7 +89,7 @@ The exact publishing setup will vary depending on your CI setup, but the overall
87
89
git config user.email "someone@example.com"
88
90
```
89
91
2. Set up git authentication. This could use tokens (covered below), SSH keys, or some other non-interactive method.
90
-
3. Set up npm authentication. This could use tokens passed on the command line (covered below), tokens set in `.npmrc`, or some other method.
92
+
3. Set up npm authentication. This could use [trusted publishing](https://docs.npmjs.com/trusted-publishers), tokens set in `.npmrc`, tokens passed on the command line (covered below), or some other method.
91
93
4. Run `beachball publish`!
92
94
93
95
### GitHub repo + GitHub Actions
@@ -98,39 +100,35 @@ This sample assumes the following:
98
100
99
101
- An environment called `release` (set up [as described above](#storing-tokens)) with the following secrets:
100
102
-`REPO_PAT`: A GitHub fine-grained personal access token with write access ([as described above](#github-token))
101
-
-`NPM_TOKEN`: An npm token with write access to the package(s) and/or scope(s), such as a [fine-grained token for public npm](#npm-token)
103
+
-[Trusted publishing](https://docs.npmjs.com/trusted-publishers) is enabled for the package(s), linked to this workflow, and given access to the `release` environment.
102
104
- A repo root `package.json` script `release` which runs `beachball publish`
103
-
- The build is running on a Linux/Mac agent. (This could be easily adapted to a Windows agent with different syntax in the commands.)
104
105
105
106
Note that in GitHub Actions, it's easiest to set up authentication if you set `persist-credentials: false` when checking out code.
106
107
107
108
```yml
108
-
# Example trigger configurations (choose one or more, or another setup)
109
-
# on:
110
-
# # Release on push to main
111
-
# push:
112
-
# branches: [main]
113
-
# # Release daily (see https://crontab-generator.org/ for help with schedules)
114
-
# schedule:
115
-
# - cron: '0 8 * * *'
116
-
# # Release on manual trigger (can be used alone or with other options)
117
-
# workflow_dispatch:
109
+
# Add trigger configuration of your choice (this one is manual only)
110
+
on:
111
+
workflow_dispatch:
118
112
119
113
environment: release
120
114
121
115
# Variable syntax below assumes Linux/Mac but could be easily adapted to Windows
122
116
runs-on: ubuntu-latest
123
117
118
+
permissions:
119
+
# Required for trusted publishing
120
+
id-token: write
121
+
124
122
steps:
125
123
- name: Check out code
126
-
uses: actions/checkout@v3
124
+
uses: actions/checkout@v6
127
125
with:
128
126
# Prevent the action from storing credentials in a way that's hard to override
129
127
persist-credentials: false
130
128
131
129
# ... Other steps to prepare for publishing (install, build, test, etc) ...
132
130
133
-
# Set the name, email, and URL with PAT
131
+
# Set the name, email, and URL with PAT (use Windows variable syntax if needed)
134
132
- name: Set git credentials
135
133
run: |
136
134
git config user.name "someone"
@@ -139,11 +137,9 @@ steps:
139
137
env:
140
138
REPO_PAT: ${{ secrets.REPO_PAT }}
141
139
142
-
#Pass the token on the command line for publishing
140
+
#No token needed with trusted publishing
143
141
- name: Publish
144
-
run: npm run release -- --token "$NPM_TOKEN"
145
-
env:
146
-
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
142
+
run: npm run release
147
143
```
148
144
149
145
### GitHub repo + Azure Pipelines
@@ -156,20 +152,15 @@ This sample assumes the following:
156
152
- `REPO_PAT`: A GitHub fine-grained personal access token with write access ([as described above](#github-token))
157
153
- `NPM_TOKEN`: An npm token with write access to the package(s) and/or scope(s), such as a [fine-grained token for public npm](#npm-token)
158
154
- A repo root `package.json` script `release` which runs `beachball publish`
159
-
- The build is running on a Linux/Mac agent. (This could be easily adapted to a Windows agent with different syntax in the commands.)
155
+
- A `.npmrc` file with the following content (change the registry if needed):
156
+
```txt
157
+
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
158
+
```
160
159
161
160
```yml
162
-
# Example trigger configurations (choose one or more, or another setup)
0 commit comments