Skip to content

Update README.md #472

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.

Sign up for GitHub

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

Open
h3rmanj wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Update README.md #472

Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
4057424
docs: add more usage information
h3rmanj May 8, 2025
f805484
docs: specify some pull request events as well
h3rmanj May 8, 2025
1a6037c
docs: mention provenance in permissions
h3rmanj May 8, 2025
95d819c
docs: restructure inputs and outputs to table
h3rmanj May 9, 2025
28e399b
docs: update example versions
h3rmanj May 9, 2025
991c95c
docs: create advanced section
h3rmanj May 9, 2025
054b0de
docs: clarify base event triggers
h3rmanj May 9, 2025
6c7df09
docs: remove empty value
h3rmanj May 9, 2025
d04bdcf
docs: clarify setupGitUser
h3rmanj May 9, 2025
4a5bb6a
docs: mention @changesets/ghcommit
h3rmanj May 12, 2025
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
96 changes: 70 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,37 @@ This action for [Changesets](https://github.com/changesets/changesets) creates a

### Inputs

- publish - The command to use to build and publish packages
- version - The command to update version, edit CHANGELOG, read and delete changesets. Default to `changeset version` if not provided
- commit - The commit message to use. Default to `Version Packages`
- title - The pull request title. Default to `Version Packages`
- setupGitUser - Sets up the git user for commits as `"github-actions[bot]"`. Default to `true`
- createGithubReleases - A boolean value to indicate whether to create Github releases after `publish` or not. Default to `true`
- commitMode - 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`.
- cwd - Changes node's `process.cwd()` if the project is not located on the root. Default to `process.cwd()`
| Input | Default Value | Description |
| :--------------------- | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| `publish` | | The command to use to build and publish packages |
| `version` | `changeset version` | The command to update version, edit CHANGELOG, read and delete changesets |
| `commit` | `Version Packages` | The commit message to use |
| `title` | `Version Packages` | The pull request title |
| `setupGitUser` | `true` | Sets up the git user for commits as `"github-actions[bot]"`. No effect when using `commitMode: github-api` |
| `createGithubReleases` | `true` | A boolean value to indicate whether to create Github releases after `publish` or not |
| `commitMode` | `git-cli` | Use `"git-cli"` to push changes using the Git CLI, or `"github-api"` to push changes via the GitHub API. [More info](#github-api-commit-mode) |
| `cwd` | `process.cwd()` | Changes node's `process.cwd()` if the project is not located on the root |

### Outputs

- published - A boolean value to indicate whether a publishing has happened or not
- publishedPackages - 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"}]`
| Output | Description |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------- |
| `published` | A boolean value to indicate whether a publishing has happened or not |
| `publishedPackages` | 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"}]` |

### Permissions

If your repository has [restrictive default permissions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token), you need to set the following permissions:

```yaml
permissions:
contents: write
pull-requests: write
# uncomment this if you're publishing with provenance https://docs.npmjs.com/generating-provenance-statements
# id-token: write
```

You also need to check `Allow GitHub Actions to create and approve pull requests` in your repositories Actions settings.

### Example workflow:

Expand All @@ -42,12 +60,12 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Setup Node.js 20
uses: actions/setup-node@v3
- name: Setup Node.js 22.x
uses: actions/setup-node@v4
with:
node-version: 20
node-version: 22.x

- name: Install Dependencies
run: yarn
Expand Down Expand Up @@ -78,12 +96,12 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Setup Node.js 20.x
uses: actions/setup-node@v3
- name: Setup Node.js 22.x
uses: actions/setup-node@v4
with:
node-version: 20.x
node-version: 22.x

- name: Install Dependencies
run: yarn
Expand Down Expand Up @@ -143,12 +161,12 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Setup Node.js 20.x
uses: actions/setup-node@v3
- name: Setup Node.js 22.x
uses: actions/setup-node@v4
with:
node-version: 20.x
node-version: 22.x

- name: Install Dependencies
run: yarn
Expand Down Expand Up @@ -187,12 +205,12 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Setup Node.js 20.x
uses: actions/setup-node@v3
- name: Setup Node.js 22.x
uses: actions/setup-node@v4
with:
node-version: 20.x
node-version: 22.x

- name: Install Dependencies
run: yarn
Expand All @@ -216,3 +234,29 @@ If you are using [Yarn Plug'n'Play](https://yarnpkg.com/features/pnp), you shoul
version: yarn changeset version
...
```

## Advanced

### Triggering other workflows

When using the built-in `GITHUB_TOKEN`, tags, releases and pull requests created by this action won't trigger other workflows. From the [GitHub Docs docs](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow):
Copy link

@trueberryless trueberryless Oct 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the docs is a duplicate and it should only be one:

Suggested change
When using the built-in `GITHUB_TOKEN`, tags, releases and pull requests created by this action won't trigger other workflows. From the [GitHub Docs docs](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow):
When using the built-in `GITHUB_TOKEN`, tags, releases and pull requests created by this action won't trigger other workflows. From the [GitHub Docs](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow):


> When you use the repository's `GITHUB_TOKEN` to perform tasks, events triggered by the `GITHUB_TOKEN`, will not create a new workflow run. This prevents you from accidentally creating recursive workflow runs.

To fix this, you should use a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) or a [GitHub App token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow) for this action. You also need to set the `commitMode` input to `github-api`.

This is useful when using this action for [managing applications or non-npm packages](https://github.com/changesets/changesets/blob/main/docs/versioning-apps.md), and using tag or release triggers for custom release workflows.
Comment on lines +240 to +248
Copy link
Contributor Author

@h3rmanj h3rmanj May 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, IIRC some of the restrictions are lifted when using PAT - even with the default commitMode. Do you know what's the breakdown of what becomes possible with PAT using both modes?

Full breakdown from some testing

Variation push.branches push.tags pull_request.opened pull_request.synchronized release.published
Built-in token ❌ ❌ ❌ ❌ ❌
PAT ❌ ❌ ✅ ❌ ✅
PAT + github-api ✅ ✅ ✅ ❌ re-triggers opened instead ✅
PAT + actions/checkout PAT ✅ ✅ ✅ ✅ ✅

Not sure if I should document all these possible variations though. Personally I prefer github-api mode for the following reasons:

  • Commit signing
  • It's built-in to the action itself, so you can achieve desired result by only configuring this action
  • Once configured, it enables all event triggers, not just some

@Andarist what would you like see mentioned in the readme?


### GitHub API commit mode

When using `github-api` for the `commitMode` input, all commits and tags are GPG-signed and attributed to the user or app who owns the `GITHUB_TOKEN`.

Due to calling the GitHub API more often, you may experience hitting [the rate limits](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28). This is more likely when using changesets in multiple, large, or very active projects.

This mode uses [`@changesets/ghcommit`](https://github.com/changesets/ghcommit) to commit changes, which has some [known limitations](https://github.com/changesets/ghcommit?tab=readme-ov-file#known-limitations):

> Due to using the GitHub API to make changes to repository contents, there are some things it's not possible to commit, and where using the Git CLI is still required.
>
> - Executable files
> - Symbolic Links
> - Submodule changes