Skip to content

Commit 64b747d

Browse files
bluwybluwy
authored
Update all the docs (#703)
* Update all the docs * Fix heading
1 parent 219ea82 commit 64b747d

14 files changed

Lines changed: 306 additions & 478 deletions

File tree

‎README.md‎

Lines changed: 45 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -1,218 +1,63 @@
1-
# Changesets Release Action
1+
# Changesets GitHub Action
22

33
> [!IMPORTANT]
44
> This is the development branch for `changesets/action` v2 compatible with Changesets v3. For the v1 code compatible with Changesets v2, check out the [`maintenance/v1`](https://github.com/changesets/action/tree/maintenance/v1) branch.
55
6-
This action for [Changesets](https://github.com/changesets/changesets) creates a pull request with all of the package versions updated and changelogs updated and when there are new changesets on [your configured `baseBranch`](https://github.com/changesets/changesets/blob/main/docs/config-file-options.md#basebranch-git-branch-name), the PR will be updated. When you're ready, you can merge the pull request and you can either publish the packages to npm manually or setup the action to do it for you.
6+
This repo contains a collection of GitHub Actions for [Changesets](https://changesets.dev). Check out the [Automating Changesets](https://changesets.dev/guide/automating) guide to learn how to use these actions to automate your workflow.
77

8-
There are also sub-actions hosted in this repository. Check out their respective READMEs for more details:
8+
- [changesets/action](./README.md): (This README. See below for details.)
9+
- [changesets/action/select-mode](./select-mode/README.md): Select the mode to run a Changesets workflow.
10+
- [changesets/action/version](./version/README.md): Version packages and create or update a pull request with the changes.
11+
- [changesets/action/pack](./pack/README.md): Pack publishable packages into tarballs.
12+
- [changesets/action/publish](./publish/README.md): Publish packages to npm.
13+
- [changesets/action/pr-status](./pr-status/README.md): Generate changeset status in PRs.
14+
- [changesets/action/pr-comment](./pr-comment/README.md): Create or update comments on PRs.
915

10-
- [pr-status](./pr-status/README.md): Generate changeset status in PRs.
11-
- [pr-comment](./pr-comment/README.md): Comment on PRs.
16+
## changesets/action
1217

13-
## Usage
18+
This action handles versioning and publishing of packages. It's the equivalent of setting up the `changesets/action/select-mode`, `changesets/action/version`, and `changesets/action/publish` actions in a workflow, but with the required permissions combined.
1419

15-
### Inputs
20+
If using [trusted publishing](https://docs.npmjs.com/trusted-publishers), it's recommended to set up the individual sub-actions instead to tighten publish permissions.
1621

17-
- publish-script - The command to use to build and publish packages
18-
- version-script - The command to update version, edit CHANGELOG, read and delete changesets. Default to `changeset version` if not provided
19-
- commit-message - The commit message to use. Default to `Version Packages`
20-
- pr-title - The pull request title. Default to `Version Packages`
21-
- create-github-releases - A boolean value to indicate whether to create Github releases after `publish` or not. Default to `true`
22-
- push-git-tags - A boolean value to indicate whether to create git tags after `publish` or not. Default to `true`
23-
- commit-mode - Specifies the commit mode. Use `"git-cli"` to push changes using the Git CLI, or `"github-api"` to push changes via the GitHub API. When using `"github-api"`, all commits and tags are GPG-signed and attributed to the user or app who owns the `GITHUB_TOKEN`. Default to `git-cli`
24-
- cwd - Changes node's `process.cwd()` if the project is not located on the root. Default to `process.cwd()`
25-
- pr-draft - Controls draft PR behavior. Use `create` to create new version PRs as draft, or `always` to also convert existing version PRs back to draft when updating them. By default, version PRs are not forced into draft mode
26-
- github-token - Passes a custom GitHub token
22+
### Requirements
2723

28-
Before creating local commits or annotated tags, the action preserves complete
29-
Git author and committer identities configured through the environment or Git
30-
configuration. If either identity is unavailable, it configures
31-
`github-actions[bot]` as a fallback.
24+
- Needs repo checked out and `@changesets/cli` installed
25+
- [Job permissions][job-permissions]:
26+
- `contents: write`: to commit version changes
27+
- `pull-requests: write`: to create pull request
28+
- `id-token: write`: if using [trusted publishing](https://docs.npmjs.com/trusted-publishers)
29+
- [Workflow triggers][workflow-triggers]: _any_
3230

33-
### Outputs
31+
### Usage
3432

35-
- published - A boolean value to indicate whether a publishing has happened or not
36-
- published-packages - A JSON array to present the published packages. The format is `[{"name": "@xx/xx", "version": "1.2.0"}, {"name": "@xx/xy", "version": "0.8.9"}]`
33+
> [!TIP]
34+
> Check out [the docs](https://changesets.dev/guide/automating#how-do-i-run-the-version-and-publish-commands) to learn how to set up the version and publish workflow.
3735
38-
### Example workflow
36+
### API
3937

40-
#### Without Publishing
38+
<!-- api-start -->
4139

42-
Create a file at `.github/workflows/release.yml` with the following content.
40+
| Inputs | Description |
41+
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42+
| `github-token` | The GitHub token to use for authentication. Defaults to the GitHub-provided token. |
43+
| `publish-script` | The command to use to build and publish packages |
44+
| `version-script` | The command to update version, edit CHANGELOG, read and delete changesets. Default to `changeset version` if not provided |
45+
| `commit-message` | The commit message. Default to `Version Packages` |
46+
| `pr-title` | The pull request title. Default to `Version Packages` |
47+
| `pr-draft` | Controls draft PR behavior. Use 'create' to create new version PRs as draft, or 'always' to also convert existing version PRs back to draft when updating them. |
48+
| `pr-base-branch` | Sets the base branch of the PR. Defaults to `github.ref_name`. |
49+
| `create-github-releases` | Whether to create Github releases after publish |
50+
| `push-git-tags` | Whether to create git tags after publish. If `create-github-releases` is set to `true`, this option will also always be `true`. |
51+
| `commit-mode` | An enum to specify the commit mode. Use "git-cli" to push changes using the Git CLI, or "github-api" to push changes via the GitHub API. When using "github-api", all commits and tags are signed using GitHub's GPG key and attributed to the user or app who owns the GITHUB_TOKEN. |
4352

44-
```yml
45-
name: Release
53+
| Outputs | Description |
54+
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
55+
| `published` | A "true" or "false" string value to indicate whether a publishing is happened or not |
56+
| `published-packages` | A JSON array to present the published packages. The format is `[{"name": "@xx/xx", "version": "1.2.0"}, {"name": "@xx/xy", "version": "0.8.9"}]` |
57+
| `has-changesets` | A "true" or "false" string value about whether there were changesets. Useful if you want to create your own publishing functionality. |
58+
| `pr-number` | The pull request number that was created or updated |
4659

47-
on:
48-
push:
49-
branches:
50-
- main
60+
<!-- api-end -->
5161

52-
concurrency: ${{ github.workflow }}-${{ github.ref }}
53-
54-
jobs:
55-
release:
56-
name: Release
57-
runs-on: ubuntu-latest
58-
steps:
59-
- name: Checkout Repo
60-
uses: actions/checkout@v6
61-
62-
- name: Setup pnpm
63-
uses: pnpm/action-setup@v6
64-
65-
- name: Setup Node.js 26
66-
uses: actions/setup-node@v6
67-
with:
68-
node-version: 26
69-
70-
- name: Install Dependencies
71-
run: pnpm install --frozen-lockfile
72-
73-
- name: Create Release Pull Request
74-
uses: changesets/action@v2
75-
```
76-
77-
#### With Publishing
78-
79-
Check the [npm authentication guide](./docs/set-up-npm-auth.md) to set up publishing to npm. After that, an example workflow with publishing may look like this:
80-
81-
```yml
82-
name: Release
83-
84-
on:
85-
push:
86-
branches:
87-
- main
88-
89-
concurrency: ${{ github.workflow }}-${{ github.ref }}
90-
91-
jobs:
92-
release:
93-
name: Release
94-
runs-on: ubuntu-latest
95-
steps:
96-
- name: Checkout Repo
97-
uses: actions/checkout@v6
98-
99-
- name: Setup pnpm
100-
uses: pnpm/action-setup@v6
101-
102-
- name: Setup Node.js 26
103-
uses: actions/setup-node@v6
104-
with:
105-
node-version: 26
106-
registry-url: https://registry.npmjs.org/ # makes the action set up npm authentication
107-
108-
- name: Install Dependencies
109-
run: pnpm install --frozen-lockfile
110-
111-
- name: Create Release Pull Request or Publish to npm
112-
id: changesets
113-
uses: changesets/action@v2
114-
with:
115-
# This expects you to have a script called release which does a build for your packages and calls changeset publish
116-
publish-script: pnpm release
117-
env:
118-
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
119-
```
120-
121-
#### Custom Publishing
122-
123-
If you want to hook into when publishing should occur but have your own publishing functionality, you can utilize the `hasChangesets` output.
124-
125-
Note that you might need to account for things already being published in your script because a commit without any new changesets can always land on your base branch after a successful publish. In such a case you need to figure out on your own how to skip over the actual publishing logic or handle errors gracefully as most package registries won't allow you to publish over already published version.
126-
127-
```yml
128-
name: Release
129-
130-
on:
131-
push:
132-
branches:
133-
- main
134-
135-
jobs:
136-
release:
137-
name: Release
138-
runs-on: ubuntu-latest
139-
steps:
140-
- name: Checkout Repo
141-
uses: actions/checkout@v6
142-
143-
- name: Setup pnpm
144-
uses: pnpm/action-setup@v6
145-
146-
- name: Setup Node.js 26
147-
uses: actions/setup-node@v6
148-
with:
149-
node-version: 26
150-
registry-url: https://registry.npmjs.org/ # makes the action set up npm authentication
151-
152-
- name: Install Dependencies
153-
run: pnpm install --frozen-lockfile
154-
155-
- name: Create Release Pull Request or Publish to npm
156-
id: changesets
157-
uses: changesets/action@v2
158-
159-
- name: Publish
160-
if: steps.changesets.outputs.hasChangesets == 'false'
161-
# You can do something when a publish should happen.
162-
run: pnpm publish
163-
env:
164-
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
165-
```
166-
167-
#### With version script
168-
169-
If you need to add additional logic to the version command, you can do so by using a version script.
170-
171-
If the version script is present, this action will run that script instead of `changeset version`, so please make sure that your script calls `changeset version` at some point. All the changes made by the script will be included in the PR.
172-
173-
```yml
174-
name: Release
175-
176-
on:
177-
push:
178-
branches:
179-
- main
180-
181-
concurrency: ${{ github.workflow }}-${{ github.ref }}
182-
183-
jobs:
184-
release:
185-
name: Release
186-
runs-on: ubuntu-latest
187-
steps:
188-
- name: Checkout Repo
189-
uses: actions/checkout@v6
190-
191-
- name: Setup pnpm
192-
uses: pnpm/action-setup@v6
193-
194-
- name: Setup Node.js 26
195-
uses: actions/setup-node@v6
196-
with:
197-
node-version: 26
198-
199-
- name: Install Dependencies
200-
run: pnpm install --frozen-lockfile
201-
202-
- name: Create Release Pull Request
203-
uses: changesets/action@v2
204-
with:
205-
# this expects you to have a npm script called version that runs some logic and then calls `changeset version`.
206-
version-script: pnpm version
207-
```
208-
209-
#### With Yarn 2 / Plug'n'Play
210-
211-
If you are using [Yarn Plug'n'Play](https://yarnpkg.com/features/pnp), you should use a custom `version` command so that the action can resolve the `changeset` CLI:
212-
213-
```yaml
214-
- uses: changesets/action@v2
215-
with:
216-
version-script: yarn changeset version
217-
# ...
218-
```
62+
[job-permissions]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions
63+
[workflow-triggers]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows

‎action.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,12 +48,12 @@ inputs:
4848
default: "git-cli"
4949
outputs:
5050
published:
51-
description: A boolean value to indicate whether a publishing is happened or not
51+
description: A "true" or "false" string value to indicate whether a publishing is happened or not
5252
published-packages:
5353
description: >
5454
A JSON array to present the published packages. The format is `[{"name": "@xx/xx", "version": "1.2.0"}, {"name": "@xx/xy", "version": "0.8.9"}]`
5555
has-changesets:
56-
description: A boolean about whether there were changesets. Useful if you want to create your own publishing functionality.
56+
description: A "true" or "false" string value about whether there were changesets. Useful if you want to create your own publishing functionality.
5757
pr-number:
5858
description: The pull request number that was created or updated
5959
branding:

0 commit comments

Comments
 (0)