From 197ca89529ba34f03faca1f39bd0e1f491d83585 Mon Sep 17 00:00:00 2001 From: Jim Myhrberg Date: Sun, 7 May 2023 20:52:40 +0100 Subject: [PATCH] docs(readme): fully flesh out readme --- Makefile | 8 ++ README.md | 240 ++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 222 insertions(+), 26 deletions(-) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c3f277e --- /dev/null +++ b/Makefile @@ -0,0 +1,8 @@ +.PHONY: action-docs +action-docs: check-npx + npx --yes action-docs --update-readme + +.PHONY: check-npx +check-npx: + $(if $(shell which npx),,\ + $(error No npx execuable found in PATH, please install NodeJS)) diff --git a/README.md b/README.md index 9122986..7b5a37d 100644 --- a/README.md +++ b/README.md @@ -2,42 +2,64 @@ release-please-manifest-action -Opinionated [action][1] for running [release-please][2] in [manifest mode][3] -with support for authenticating as a [GitHub App][4]. +

+ + Opinionated action for running release-please in manifest mode. + +

-Implemented as a composite action which wraps [release-please-action][5] and -[github-app-token][6] actions, with opinionated default settings. +

+ + GitHub tag (latest SemVer) + + + GitHub issues + + + GitHub pull requests + + + License Status + +

-[1]: https://github.com/features/actions -[2]: https://github.com/googleapis/release-please -[3]: +A composite action which wraps [release-please-action][] and +[github-app-token][] actions, with opinionated default settings focused on +running [release-please][] in [manifest mode][]. + +[release-please-action]: + https://github.com/google-github-actions/release-please-action +[github-app-token]: https://github.com/tibdex/github-app-token +[release-please]: https://github.com/googleapis/release-please +[manifest mode]: https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md -[4]: https://docs.github.com/en/apps/overview -[5]: https://github.com/google-github-actions/release-please-action -[6]: https://github.com/tibdex/github-app-token -## Features +# Features -- Makes it easy to run release-please as a GitHub App, allowing checks to run on - Release Pull Requests. -- Defaults to placing release-please config and manifest files within the - `.github` folder instead of in the repository root: +- Focuses on and only supports running release-please's manifest command. +- Optionally supports having release-please authenticate as a GitHub App. +- By default places release-please config and manifest files within the + top-level `.github` directory instead of in the repository root: - `.github/release-please-manifest.json` - `.github/release-please-config.json` -## To-Do +# Examples -- [ ] Verify stability of this action. -- [ ] Setup CI releases using itself, so the action can be referred to with - `@v1` instead of `@main`. +## Basic (Actions Token) -## Examples +This example will have release-please authenticate using `secrets.GITHUB_TOKEN` +that is automatically available to all actions. -The below example assumes you have secrets already setup for the app ID and -private key. +This will prevent checks / GitHub Actions running against any Release Pull +Requests raised by release-please. This is a feature of GitHub as a means of +trying to avoid GitHub Actions jobs triggering themselves, causing an endless +loop. -If you do not want to authenticate as a GitHub App, simply do not provide -`app-id` and `private-key` inputs. +If you need checks to run against Release Pull Requests, you will need to have +release-please authenticate with a Personal Access Token (PAT), or as a GitHub +App. + + ```yaml on: push @@ -46,13 +68,122 @@ jobs: runs-on: ubuntu-latest if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' steps: - - uses: jimeh/release-please-action@main + - uses: jimeh/release-please-action@v0 +``` + + + +
+The above is equivalent to: + +```yaml +on: push +jobs: + release-please: + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' + steps: + - uses: google-github-actions/release-please-action@v3 + id: release-please + with: + command: manifest + config-file: .github/release-please-config.json + manifest-file: .github/release-please-manifest.json +``` + +_Note: Outputs are not included in this equivalence example._ + +
+ +## Personal Access Token (PAT) Authentication + +This example will have release-please authenticate with a user's Personal Access +Token (PAT), performing all operations on behalf of that user. Allowing checks / +GitHub Actions to run against Release Pull Requests. + +It is common to have a dedicated "bot" user created for these purposes. But +within paid organizations, that means an extra user seat needs to be paid for. +In that case you might prefer using a GitHub App instead. + + + +```yaml +on: push +jobs: + release-please: + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' + steps: + - uses: jimeh/release-please-action@v0 + with: + token: ${{ secrets.RELEASE_PAT_TOKEN }} +``` + + + +
+The above is equivalent to: + +```yaml +on: push +jobs: + release-please: + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' + steps: + - uses: google-github-actions/release-please-action@v3 + id: release-please + with: + token: ${{ secrets.RELEASE_PAT_TOKEN }} + command: manifest + config-file: .github/release-please-config.json + manifest-file: .github/release-please-manifest.json +``` + +_Note: Outputs are not included in this equivalence example._ + +
+ +## GitHub App Authentication + +This example will have release-please authenticate as a GitHub App, performing +all operations on behalf of the app. + +This has a few benefits compared to using the token provided by GitHub Actions +or a user's personal access token: + +- It allows checks / GitHub Actions to run against the Release Pull Requests + raised by release-please. +- An app can be given permissions to access all repos within an organization. +- Compared to creating a separate "bot" user, paid organizations do not need to + pay for an extra user seat when using an app. + +Below we assume you have already setup `RELEASE_BOT_APP_ID` and +`RELEASE_BOT_PRIVATE_KEY` secrets in the repository or organization. + +To set the private key secret, it is easiest to base64 encode the contents of +`*.pem` file you get from the GitHub App's configuration page. The base64 +encoded string should not have any line-breaks. + + + +```yaml +on: push +jobs: + release-please: + runs-on: ubuntu-latest + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' + steps: + - uses: jimeh/release-please-action@v0 with: app-id: ${{ secrets.RELEASE_BOT_APP_ID }} private-key: ${{ secrets.RELEASE_BOT_PRIVATE_KEY }} ``` -The above, is equivalent to: + + +
+The above is equivalent to: ```yaml on: push @@ -74,3 +205,60 @@ jobs: config-file: .github/release-please-config.json manifest-file: .github/release-please-manifest.json ``` + +_Note: Outputs are not included in this equivalence example._ + +
+ +# Reference + + + +## Inputs + +| parameter | description | required | default | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------ | +| token | GitHub token used to authenticate. | `false` | ${{ github.token }} | +| app-id | ID of the GitHub App to use for authentication. If set, takes precedence over token input. | `false` | | +| private-key | Private key of the GitHub App (can be Base64 encoded). Required when app-id is provided. | `false` | | +| installation-id | ID of the installation for which the app token will be requested. Defaults to the ID of the repository's installation. | `false` | | +| permissions | JSON-stringified permissions granted to the app token. Defaults to all the GitHub app permissions, see: https://docs.github.com/en/rest/apps/apps#create-an-installation-access-token-for-an-app | `false` | | +| github-api-url | Configure github API URL. | `false` | ${{ github.api_url }} | +| repository | The full name of the repository to operate on in owner/repo format. Defaults to the current repository. | `false` | ${{ github.repository }} | +| default-branch | Branch to open pull release PR against. Defaults to the repository's default branch. | `false` | | +| config-file | Pat to config file within the project. | `false` | .github/release-please-config.json | +| manifest-file | Path to manifest file within the project. | `false` | .github/release-please-manifest.json | + + + + + +## Outputs + +| parameter | description | +| ---------------- | -------------------------------------------------------- | +| release_created | Whether or not a release was created. | +| releases_created | Whether or not a release was created. | +| id | Release ID. | +| name | Release name. | +| tag_name | Release tag name. | +| sha | Release sha | +| body | Release body. | +| html_url | Release URL. | +| draft | Whether or not the release is a draft. | +| upload_url | Release upload URL. | +| path | Path that was released. | +| version | Version that was released. | +| major | Major version that was released. | +| minor | Minor version that was released. | +| patch | Patch version that was released. | +| paths_released | Paths that were released. | +| pr | Pull request number. | +| prs | Pull request numbers. | +| release-please | All outputs from release-please action as a JSON string. | + + + +# License + +[CC0 1.0 Universal](http://creativecommons.org/publicdomain/zero/1.0/)