diff --git a/README.md b/README.md index 1bad65de..9b16ad29 100644 --- a/README.md +++ b/README.md @@ -1,218 +1,63 @@ -# Changesets Release Action +# Changesets GitHub Action > [!IMPORTANT] > 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. -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. +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. -There are also sub-actions hosted in this repository. Check out their respective READMEs for more details: +- [changesets/action](./README.md): (This README. See below for details.) +- [changesets/action/select-mode](./select-mode/README.md): Select the mode to run a Changesets workflow. +- [changesets/action/version](./version/README.md): Version packages and create or update a pull request with the changes. +- [changesets/action/pack](./pack/README.md): Pack publishable packages into tarballs. +- [changesets/action/publish](./publish/README.md): Publish packages to npm. +- [changesets/action/pr-status](./pr-status/README.md): Generate changeset status in PRs. +- [changesets/action/pr-comment](./pr-comment/README.md): Create or update comments on PRs. -- [pr-status](./pr-status/README.md): Generate changeset status in PRs. -- [pr-comment](./pr-comment/README.md): Comment on PRs. +## changesets/action -## Usage +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. -### Inputs +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. -- publish-script - The command to use to build and publish packages -- version-script - The command to update version, edit CHANGELOG, read and delete changesets. Default to `changeset version` if not provided -- commit-message - The commit message to use. Default to `Version Packages` -- pr-title - The pull request title. Default to `Version Packages` -- create-github-releases - A boolean value to indicate whether to create Github releases after `publish` or not. Default to `true` -- push-git-tags - A boolean value to indicate whether to create git tags after `publish` or not. Default to `true` -- 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` -- cwd - Changes node's `process.cwd()` if the project is not located on the root. Default to `process.cwd()` -- 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 -- github-token - Passes a custom GitHub token +### Requirements -Before creating local commits or annotated tags, the action preserves complete -Git author and committer identities configured through the environment or Git -configuration. If either identity is unavailable, it configures -`github-actions[bot]` as a fallback. +- Needs repo checked out and `@changesets/cli` installed +- [Job permissions][job-permissions]: + - `contents: write`: to commit version changes + - `pull-requests: write`: to create pull request + - `id-token: write`: if using [trusted publishing](https://docs.npmjs.com/trusted-publishers) +- [Workflow triggers][workflow-triggers]: _any_ -### Outputs +### Usage -- published - A boolean value to indicate whether a publishing has happened or not -- 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"}]` +> [!TIP] +> 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. -### Example workflow +### API -#### Without Publishing + -Create a file at `.github/workflows/release.yml` with the following content. +| Inputs | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `github-token` | The GitHub token to use for authentication. Defaults to the GitHub-provided token. | +| `publish-script` | The command to use to build and publish packages | +| `version-script` | The command to update version, edit CHANGELOG, read and delete changesets. Default to `changeset version` if not provided | +| `commit-message` | The commit message. Default to `Version Packages` | +| `pr-title` | The pull request title. Default to `Version Packages` | +| `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. | +| `pr-base-branch` | Sets the base branch of the PR. Defaults to `github.ref_name`. | +| `create-github-releases` | Whether to create Github releases after publish | +| `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`. | +| `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. | -```yml -name: Release +| Outputs | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `published` | A "true" or "false" string value to indicate whether a publishing is happened or not | +| `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"}]` | +| `has-changesets` | A "true" or "false" string value about whether there were changesets. Useful if you want to create your own publishing functionality. | +| `pr-number` | The pull request number that was created or updated | -on: - push: - branches: - - main + -concurrency: ${{ github.workflow }}-${{ github.ref }} - -jobs: - release: - name: Release - runs-on: ubuntu-latest - steps: - - name: Checkout Repo - uses: actions/checkout@v6 - - - name: Setup pnpm - uses: pnpm/action-setup@v6 - - - name: Setup Node.js 26 - uses: actions/setup-node@v6 - with: - node-version: 26 - - - name: Install Dependencies - run: pnpm install --frozen-lockfile - - - name: Create Release Pull Request - uses: changesets/action@v2 -``` - -#### With Publishing - -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: - -```yml -name: Release - -on: - push: - branches: - - main - -concurrency: ${{ github.workflow }}-${{ github.ref }} - -jobs: - release: - name: Release - runs-on: ubuntu-latest - steps: - - name: Checkout Repo - uses: actions/checkout@v6 - - - name: Setup pnpm - uses: pnpm/action-setup@v6 - - - name: Setup Node.js 26 - uses: actions/setup-node@v6 - with: - node-version: 26 - registry-url: https://registry.npmjs.org/ # makes the action set up npm authentication - - - name: Install Dependencies - run: pnpm install --frozen-lockfile - - - name: Create Release Pull Request or Publish to npm - id: changesets - uses: changesets/action@v2 - with: - # This expects you to have a script called release which does a build for your packages and calls changeset publish - publish-script: pnpm release - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} -``` - -#### Custom Publishing - -If you want to hook into when publishing should occur but have your own publishing functionality, you can utilize the `hasChangesets` output. - -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. - -```yml -name: Release - -on: - push: - branches: - - main - -jobs: - release: - name: Release - runs-on: ubuntu-latest - steps: - - name: Checkout Repo - uses: actions/checkout@v6 - - - name: Setup pnpm - uses: pnpm/action-setup@v6 - - - name: Setup Node.js 26 - uses: actions/setup-node@v6 - with: - node-version: 26 - registry-url: https://registry.npmjs.org/ # makes the action set up npm authentication - - - name: Install Dependencies - run: pnpm install --frozen-lockfile - - - name: Create Release Pull Request or Publish to npm - id: changesets - uses: changesets/action@v2 - - - name: Publish - if: steps.changesets.outputs.hasChangesets == 'false' - # You can do something when a publish should happen. - run: pnpm publish - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} -``` - -#### With version script - -If you need to add additional logic to the version command, you can do so by using a version script. - -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. - -```yml -name: Release - -on: - push: - branches: - - main - -concurrency: ${{ github.workflow }}-${{ github.ref }} - -jobs: - release: - name: Release - runs-on: ubuntu-latest - steps: - - name: Checkout Repo - uses: actions/checkout@v6 - - - name: Setup pnpm - uses: pnpm/action-setup@v6 - - - name: Setup Node.js 26 - uses: actions/setup-node@v6 - with: - node-version: 26 - - - name: Install Dependencies - run: pnpm install --frozen-lockfile - - - name: Create Release Pull Request - uses: changesets/action@v2 - with: - # this expects you to have a npm script called version that runs some logic and then calls `changeset version`. - version-script: pnpm version -``` - -#### With Yarn 2 / Plug'n'Play - -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: - -```yaml -- uses: changesets/action@v2 - with: - version-script: yarn changeset version - # ... -``` +[job-permissions]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions +[workflow-triggers]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows diff --git a/action.yml b/action.yml index b225c6f8..04fcf068 100644 --- a/action.yml +++ b/action.yml @@ -48,12 +48,12 @@ inputs: default: "git-cli" outputs: published: - description: A boolean value to indicate whether a publishing is happened or not + description: A "true" or "false" string value to indicate whether a publishing is happened or not published-packages: description: > 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"}]` has-changesets: - description: A boolean about whether there were changesets. Useful if you want to create your own publishing functionality. + description: A "true" or "false" string value about whether there were changesets. Useful if you want to create your own publishing functionality. pr-number: description: The pull request number that was created or updated branding: diff --git a/docs/set-up-npm-auth.md b/docs/set-up-npm-auth.md deleted file mode 100644 index 6c5b3c84..00000000 --- a/docs/set-up-npm-auth.md +++ /dev/null @@ -1,199 +0,0 @@ -# How to set up npm authentication - -This is a brief guide on setting up npm authentication in GitHub Actions. Most of the information below are also applicable outside of Changesets and can be referenced for other npm workflows. - -## Recommended Setup - -It is recommended by npm to use [Trusted Publishing](https://docs.npmjs.com/trusted-publishers), or [Staged Publishing](https://docs.npmjs.com/staged-publishing), or both, to securely publish packages from CI. - -Note that Staged Publishing does not work with Changesets at the moment, so it's recommended to use Trusted Publishing instead for now. Check out [its docs](https://docs.npmjs.com/trusted-publishers) for more information to set it up. - -Also, in contrary to npm's [workflow recommendation](https://docs.npmjs.com/trusted-publishers#step-2-configure-your-cicd-workflow), make sure the `id-token: write` is only set on the job that needs to publish. As such, consider splitting the build, test, publish flows etc into separate jobs. Here's an example setup with Changesets: - -```yaml -# .github/workflows/publish.yml -name: Publish - -on: - push: - branches: - - main - -permissions: {} # recommended: reset permissions - -jobs: - select-mode: - runs-on: ubuntu-latest - outputs: - mode: ${{ steps.select-mode.outputs.mode }} - publish-plan-artifact-id: ${{ steps.select-mode.outputs.publish-plan-artifact-id }} - permissions: - contents: read # to check out repo (actions/checkout) - steps: - - uses: actions/checkout@v7 - - run: npm install - - uses: changesets/action/select-mode@v2 - id: select-mode - - version: - if: needs.select-mode.outputs.mode == 'version' - needs: select-mode - runs-on: ubuntu-latest - outputs: - version-dir-artifact-id: ${{ steps.version.outputs.version-dir-artifact-id }} - permissions: - contents: read # to check out repo (actions/checkout) - steps: - - uses: actions/checkout@v7 - - run: npm install - - uses: changesets/action/version@v2 - id: version - - pack: - if: needs.select-mode.outputs.mode == 'publish' - needs: select-mode - runs-on: ubuntu-latest - outputs: - pack-dir-artifact-id: ${{ steps.pack.outputs.pack-dir-artifact-id }} - permissions: - contents: read # to check out repo (actions/checkout) - steps: - - uses: actions/checkout@v7 - - run: npm install - - run: npm build - - uses: changesets/action/pack@v2 - id: pack - with: - publish-plan-artifact-id: ${{ needs.select-mode.outputs.publish-plan-artifact-id }} - - publish: - needs: pack - runs-on: ubuntu-latest - permissions: - id-token: write # for trusted publishing (changesets/action) - steps: - - uses: changesets/action/publish@v2 - with: - pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }} -``` - -## Token-based Publishing - -> [!CAUTION] -> Token-based publishing (with [Granular Access Tokens](https://docs.npmjs.com/about-access-tokens#about-granular-access-tokens)) is no longer recommended, with many restrictions that make it difficult to use in CI workflows. For example: -> -> - They expire after a maximum of 90 days, which requires periodic manual token rotation. -> - 2FA-bypass tokens are [being deprecated](https://github.blog/changelog/2026-07-08-npm-install-time-security-and-gat-bypass2fa-deprecation/#2fa-bypass-tokens-will-no-longer-publish-directly) and will soon be not allowed to publish packages with 2FA enabled. -> -> However, if you're using a different npm-compatible registry that does not support Trusted Publishing or Staged Publishing, you may still opt for token-based publishing. Check out the [next section](#token-based-publishing) for more information. - -You'll need an [npm token](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) with "Bypass two-factor authentication" checked (to prevent npm requesting 2FA in CI). [Add this token as a secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) in your GitHub repo with the name `NPM_TOKEN` so it can be used in the workflow below. - -In most cases, you can use [actions/setup-node](https://github.com/actions/setup-node) to set up token-based authentication automatically. - -```yaml -# .github/workflows/publish.yml -name: Publish - -on: - push: - branches: - - main - -permissions: {} # recommended: reset permissions - -jobs: - # ... other jobs like select-mode and version - publish: - if: needs.select-mode.outputs.mode == 'publish' - needs: select-mode - runs-on: ubuntu-latest - permissions: - contents: read # to check out repo (actions/checkout) - steps: - - uses: actions/checkout@v7 - - uses: actions/setup-node@v7 - with: - node-version: 24 - registry-url: https://registry.npmjs.org/ # set this option to set up npm authentication - - run: npm install - - run: npm build - - uses: changesets/action/publish@v2 - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # pass the token here -``` - -> [!TIP] -> Pass `registry-url: https://npm.pkg.github.com/` and `NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` to publish to the GitHub Package Registry instead of npm. - -Internally, `actions/setup-node` will set up a `.npmrc` file that looks like this: - -```ini -//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN} -``` - -This syntax allows to authenticate with the npm registry only when the `NODE_AUTH_TOKEN` environment variable is set, which is the safer approach than storing the token directly in the `.npmrc` file. - -### Manual Setup - -For advanced use cases, you can also set up the [`~/.npmrc` file](https://docs.npmjs.com/cli/configuring-npm/npmrc) manually. Make sure to remove the `registry-url` option from `actions/setup-node` to prevent conflicts with your custom `.npmrc` file. - -For example, if you need to publish different scopes to different registries, you can set up the `~/.npmrc` file like below: - -```yaml -- run: | - cat << 'EOF' > ~/.npmrc - - # For unscoped packages, publish to the default npm registry - //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN} - - # For @foo/* packages, publish to a custom registry - @foo:registry=https://my-registry.com/ - //my-registry.com/:_authToken=${NODE_FOO_AUTH_TOKEN} - - # For @bar/* packages, publish to the GitHub Package Registry - @bar:registry=https://npm.pkg.github.com/ - //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN} - - EOF -``` - -### Package Managers Edge Cases - -#### pnpm - -An `.npmrc` file in a project directory with pnpm does not support environment variables due to [security reasons](https://pnpm.io/blog/2026/06/11/env-variables-in-repository-npmrc). As such, it's recommended to set up in the home directory instead. This is also the general recommendation for other package managers to not mix potential existing config setups in projects. - -#### yarn - -[Yarn](https://yarnpkg.com) does not support the `.npmrc` file, compared to every other package managers that do. To set up authentication for yarn, use a [`~/.yarnrc.yml` file](https://yarnpkg.com/configuration/yarnrc) instead: - -```yaml -- run: | - cat << 'EOF' > ~/.yarnrc.yml - npmAuthToken: "${NODE_AUTH_TOKEN}" - EOF -``` - -For advanced use cases, similar to the `.npmrc` example above, the equivalent looks something like this: - -```yaml -- run: | - cat << 'EOF' > ~/.yarnrc.yml - - npmAuthToken: "${NODE_AUTH_TOKEN}" - - npmScopes: - foo: - npmRegistryServer: "https://my-registry.com/" - npmAuthToken: "${NODE_FOO_AUTH_TOKEN}" - bar: - npmRegistryServer: "https://npm.pkg.github.com/" - npmAuthToken: "${GITHUB_TOKEN}" - - EOF -``` - -#### Miscellaneous - -Other package managers may also support (or recommend) configuring the tokens in their own configuration files. Check their documentation for more information. diff --git a/pack/README.md b/pack/README.md index 1824a561..ee7709d7 100644 --- a/pack/README.md +++ b/pack/README.md @@ -1,3 +1,31 @@ # changesets/action/pack -TODO +This action packs publishable packages into tarballs, complements [changesets/action/publish](../publish/README.md) to publish them in a later step. + +## Requirements + +- Needs repo checked out and `@changesets/cli` installed +- [Job permissions][job-permissions]: _none_ +- [Workflow triggers][workflow-triggers]: _any_ + +## Usage + +> [!TIP] +> 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. + +## API + + + +| Inputs | Description | +| -------------------------- | --------------------------------------------------------------------- | +| `publish-plan-artifact-id` | Artifact id for a publish plan generated by the select-mode subaction | + +| Outputs | Description | +| ---------------------- | ------------------------------------------- | +| `pack-dir-artifact-id` | Artifact id for the packed output directory | + + + +[job-permissions]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions +[workflow-triggers]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows diff --git a/package.json b/package.json index 620ba2b0..861f1104 100644 --- a/package.json +++ b/package.json @@ -13,9 +13,10 @@ "format": "oxfmt --check", "format:fix": "oxfmt", "changeset": "changeset", - "bump": "node --experimental-strip-types ./scripts/bump.ts", - "release": "node --experimental-strip-types ./scripts/release.ts", - "release:pr": "node --experimental-strip-types ./scripts/release-pr.ts" + "bump": "node ./scripts/bump.ts", + "update-readme": "node ./scripts/update-readme.ts", + "release": "node ./scripts/release.ts", + "release:pr": "node ./scripts/release-pr.ts" }, "dependencies": { "@actions/artifact": "^6.2.1", @@ -47,7 +48,8 @@ "oxfmt": "^0.48.0", "rolldown": "^1.0.1", "typescript": "^6.0.3", - "vitest": "^4.1.6" + "vitest": "^4.1.6", + "yaml": "^2.9.0" }, "engines": { "node": ">=24" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c4996e2f..44dc466a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -98,6 +98,9 @@ importers: vitest: specifier: ^4.1.6 version: 4.1.6(@types/node@24.12.4)(vite@8.0.13) + yaml: + specifier: ^2.9.0 + version: 2.9.0 packages: diff --git a/pr-comment/README.md b/pr-comment/README.md index 268ec2ef..8c5c3c15 100644 --- a/pr-comment/README.md +++ b/pr-comment/README.md @@ -1,16 +1,28 @@ -# @changesets/action/pr-comment +# changesets/action/pr-comment -A simple GitHub Action to comment on PRs aimed to complement [`@changesets/action/pr-status`](../pr-status/README.md). +This action creates or updates comments on PRs, aimed to complement [changesets/action/pr-status](../pr-status/README.md). -This action is intentionally simple without advanced features. Check out other actions if so, such as [mshick/add-pr-comment](https://github.com/marketplace/actions/add-pr-comment) and [peter-evans/create-or-update-comment](https://github.com/marketplace/actions/create-or-update-comment). +Its features are kept intentionally simple. For advanced usecases, check out other actions such as [mshick/add-pr-comment](https://github.com/marketplace/actions/add-pr-comment) and [peter-evans/create-or-update-comment](https://github.com/marketplace/actions/create-or-update-comment). -See the [action metadata](action.yml) for details on the inputs and outputs. +## Requirements -## Example setup +- [Job permissions][job-permissions]: + - `pull-requests: write`: to create and update comments on PRs +- [Workflow triggers][workflow-triggers]: + - [`pull_request`][trigger-pull-request] + - [`pull_request_target`][trigger-pull-request-target] -```yaml -name: PR Comment +> [!CAUTION] +> **Do not run untrusted code** when using the `pull_request_target` event. +> +> `pull_request_target` can be useful to support PRs from forks, however it enables write permissions by default which can be a security risk if untrusted code is executed and the permissions aren't scoped down. + +## Usage + +> [!TIP] +> Check out [the docs](https://changesets.dev/guide/automating#non-blocking) to learn how to set up commenting changesets status on PRs. +```yaml on: pull_request: @@ -18,21 +30,25 @@ jobs: pr-comment: runs-on: ubuntu-slim permissions: - pull-requests: write # to create and update comments on PRs + pull-requests: write # to create and update comments on PRs (changesets/action/pr-comment) steps: - - uses: changesets/action/pr-comment@v1 + - name: Comment on PR + uses: changesets/action/pr-comment@v2 with: body: Hello world! ``` -When called repeatedly, the action will update the comment it created by default. If you use this action to create different types of comments, pass an `update-id` value to differentiate them. +If the action is called again for the same PR, for example, if called in another workflow run, it will update the comment it created by default. + +If you use the action to create different types of comments, pass an `update-id` value to differentiate them. ```yaml jobs: pr-comment: # ... steps: - - uses: changesets/action/pr-comment@v1 + - name: Comment on PR + uses: changesets/action/pr-comment@v2 with: body: Hello world! update-id: my-tag @@ -45,8 +61,29 @@ jobs: pr-comment: # ... steps: - - uses: changesets/action/pr-comment@v1 + - uses: changesets/action/pr-comment@v2 with: body: Hello world! update-id: "" ``` + +## API + + + +| Inputs | Description | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `github-token` | The GitHub token to use for authentication. Defaults to the GitHub-provided token. | +| `body` | **Required.** The comment body to post on the PR. | +| `update-id` | By default, the action will create and update a comment with this id. Pass a different id to create and update a new comment, or pass an empty string to disable updating comments. | + +| Outputs | Description | +| ------------ | ---------------------------------------------------------- | +| `comment-id` | The comment id of the comment that was created or updated. | + + + +[job-permissions]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions +[workflow-triggers]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows +[trigger-pull-request]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request +[trigger-pull-request-target]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target diff --git a/pr-comment/action.yml b/pr-comment/action.yml index 273da211..9a6b364e 100644 --- a/pr-comment/action.yml +++ b/pr-comment/action.yml @@ -1,5 +1,5 @@ name: Changesets - PR Comment -description: A simple GitHub Action to comment on PRs +description: Create or update comments on PRs runs: using: node24 main: ../dist/pr-comment.js diff --git a/pr-status/README.md b/pr-status/README.md index 4027a416..79a97617 100644 --- a/pr-status/README.md +++ b/pr-status/README.md @@ -1,71 +1,40 @@ # changesets/action/pr-status -This action generates the changesets status in PRs, e.g. whether it has changeset files and which packages will be released if the PR is merged. +This action generates the changesets status in PRs, for example, whether it has changeset files and which packages will be released if the PR is merged. -It requires the repo to be checked out, and automatically fetches the PR head ref into a temporary detached worktree in order to infer the changed files and packages. +It requires the repo to be checked out, and will automatically fetch the PR head ref into a temporary detached worktree in order to infer the changed files and packages. -See the [action metadata](action.yml) for details on the inputs and outputs. +## Requirements + +- Needs repo checked out +- [Job permissions][job-permissions]: _none_ +- [Workflow triggers][workflow-triggers]: + - [`pull_request`][trigger-pull-request] + - [`pull_request_target`][trigger-pull-request-target] > [!CAUTION] -> **This action uses `pull_request_target` by default to support PRs from forks.** -> > **Do not run untrusted code** when using the `pull_request_target` event. > -> The example below only **_checks out_** and **_reads_** code, and does not **_execute_** any code from the fork. -> -> Read more about the `pull_request_target` event in the [GitHub documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target). - -You can also use the [`pull_request`](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request) event if you prefer to lock permissions down and not run for PRs from forks. Make sure to add an if check to prevent the action from failing in fork PRs: - -```yaml -jobs: - pr-status: - if: github.event.pull_request.head.repo.full_name == github.repository - # ... -``` - -You can also use the [Changesets Bot](https://github.com/apps/changeset-bot) if you don't want an extra action in your repo, or are worried about the `pull_request_target` event. - -## Example setup +> `pull_request_target` can be useful to support PRs from forks, however it enables write permissions by default which can be a security risk if untrusted code is executed and the permissions aren't scoped down. -```yaml -# .github/workflows/comment-changesets-pr-status.yml -name: Comment Changesets status in PRs +[job-permissions]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions +[workflow-triggers]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows +[trigger-pull-request]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request +[trigger-pull-request-target]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request_target -on: - pull_request_target: +## Usage -permissions: {} # require explicitly stating all permissions in each job +> [!TIP] +> Check out [the docs](https://changesets.dev/guide/automating#non-blocking) to learn how to set up commenting changesets status on PRs. -concurrency: - group: ${{ github.workflow }}-${{ github.event.pull_request.number }} - cancel-in-progress: true +## API -jobs: - pr-status: - runs-on: ubuntu-slim - permissions: - contents: read # to check out files in the repo - outputs: - comment-body: ${{ steps.pr-status.outputs.comment-body }} - steps: - - name: Check out repo - uses: actions/checkout@v6 + - - name: Generate status - id: pr-status - uses: changesets/action/pr-status@v1 +Inputs: _none_ - pr-comment: - needs: pr-status - runs-on: ubuntu-slim - permissions: - pull-requests: write # to create and update comments on PRs - steps: - - name: Comment on PR - uses: changesets/action/pr-comment@v1 - with: - body: ${{ needs.pr-status.outputs.comment-body }} -``` +| Outputs | Description | +| -------------- | ------------------------------------------------------------------- | +| `comment-body` | The generated comment body to present the changesets status in PRs. | -The workflow uses [`@changesets/action/pr-comment`](../pr-comment/README.md), which is a simple GitHub Action to comment on PRs. + diff --git a/publish/README.md b/publish/README.md index 2850488a..44269cb8 100644 --- a/publish/README.md +++ b/publish/README.md @@ -1,3 +1,37 @@ # changesets/action/publish -TODO +This action publishes packages to npm. + +## Requirements + +- Needs repo checked out and `@changesets/cli` installed +- [Job permissions][job-permissions]: + - `id-token: write`: if using [trusted publishing](https://docs.npmjs.com/trusted-publishers) +- [Workflow triggers][workflow-triggers]: _any_ + +## Usage + +> [!TIP] +> 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. + +## API + + + +| Inputs | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | +| `github-token` | The GitHub token to use for authentication. Defaults to the GitHub-provided token. | +| `script` | The command to use to publish packages | +| `pack-dir-artifact-id` | Artifact id for packed publish output generated by the pack subaction | +| `create-github-releases` | Whether to create Github releases after publish | +| `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`. | + +| Outputs | Description | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `published` | A "true" or "false" string value to indicate whether a publishing has happened or not | +| `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"}]` | + + + +[job-permissions]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions +[workflow-triggers]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows diff --git a/publish/action.yml b/publish/action.yml index 809c5509..aba3946b 100644 --- a/publish/action.yml +++ b/publish/action.yml @@ -26,7 +26,7 @@ inputs: default: true outputs: published: - description: "A boolean value to indicate whether a publishing has happened or not" + description: A "true" or "false" string value to indicate whether a publishing has happened or not published-packages: description: > 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"}]` diff --git a/scripts/update-readme.ts b/scripts/update-readme.ts new file mode 100644 index 00000000..a633991f --- /dev/null +++ b/scripts/update-readme.ts @@ -0,0 +1,46 @@ +import * as fs from "node:fs/promises"; +import path from "node:path"; +import { markdownTable } from "markdown-table"; +import * as yaml from "yaml"; + +await main(); + +async function main() { + for await (const readmePath of fs.glob("**/README.md", { + exclude: ["**/node_modules/**"], + })) { + const actionPath = path.join(path.dirname(readmePath), "action.yml"); + const actionExists = await fs.stat(actionPath).catch(() => null); + if (!actionExists) continue; + + const action = yaml.parse(await fs.readFile(actionPath, "utf8")); + const inputs = action.inputs ?? {}; + const outputs = action.outputs ?? {}; + + const content = [ + renderSection("Inputs", inputs), + renderSection("Outputs", outputs), + ].join("\n\n"); + + const readme = await fs.readFile(readmePath, "utf8"); + const updated = readme.replace( + /[\s\S]*?/, + `\n\n${content}\n\n`, + ); + await fs.writeFile(readmePath, updated); + } +} + +function renderSection(title: string, entries: Record) { + const rows: string[][] = []; + for (const [name, entry] of Object.entries(entries)) { + let description = (entry.description ?? "").trim().replace(/\|/g, "\\|"); + if (entry.required) description = `**Required.** ${description}`; + rows.push([`\`${name}\``, description]); + } + if (rows.length === 0) { + return `${title}: _none_`; + } + rows.unshift([title, "Description"]); + return markdownTable(rows); +} diff --git a/select-mode/README.md b/select-mode/README.md index f741cc8c..2b5462e1 100644 --- a/select-mode/README.md +++ b/select-mode/README.md @@ -1,3 +1,30 @@ # changesets/action/select-mode -TODO +This action selects the mode to run a Changesets workflow: + +- `"version"`: Changesets are found. The workflow should version packages and create a pull request with the changes. +- `"publish"`: No changesets are found and they are publishable packages. The workflow should publish them. +- `"none"`: No changesets are found and there are no publishable packages. The workflow should do nothing. + +## Requirements + +- [Job permissions][job-permissions]: _none_ +- [Workflow triggers][workflow-triggers]: _any_ + +## Usage + +> [!TIP] +> 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. + +## API + + + +Inputs: _none_ + +| Outputs | Description | +| -------------------------- | ---------------------------------------------------------------------------- | +| `mode` | The mode to use for the current repo state: 'version', 'publish', or 'none'. | +| `publish-plan-artifact-id` | Artifact id for the generated publish plan when mode is `publish` | + + diff --git a/version/README.md b/version/README.md index f0efb2bb..77e54e93 100644 --- a/version/README.md +++ b/version/README.md @@ -1,3 +1,39 @@ # changesets/action/version -TODO +This action versions packages and creates or updates a pull request with the changes. + +## Requirements + +- Needs repo checked out and `@changesets/cli` installed +- [Job permissions][job-permissions]: + - `contents: write`: to commit version changes + - `pull-requests: write`: to create pull request +- [Workflow triggers][workflow-triggers]: _any_ + +## Usage + +> [!TIP] +> 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. + +## API + + + +| Inputs | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `github-token` | The GitHub token to use for authentication. Defaults to the GitHub-provided token. | +| `script` | The command to use to version packages | +| `commit-message` | The commit message. Default to `Version Packages` | +| `pr-title` | The pull request title. Default to `Version Packages` | +| `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. | +| `pr-base-branch` | Sets the base branch of the PR. Defaults to `github.ref_name`. | +| `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. | + +| Outputs | Description | +| ----------- | --------------------------------------------------- | +| `pr-number` | The pull request number that was created or updated | + + + +[job-permissions]: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idpermissions +[workflow-triggers]: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows