From 1281ebd51ad4a6b4731e7308bd8988b51bc9d868 Mon Sep 17 00:00:00 2001 From: Peter Evans Date: Sat, 9 Nov 2019 18:22:57 +0900 Subject: [PATCH] Update README --- README.md | 107 +++++++++++++++++++++++++++--------------------------- 1 file changed, 54 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 1f6b670..062795a 100644 --- a/README.md +++ b/README.md @@ -17,54 +17,52 @@ Create Pull Request action will: See [examples](examples.md) for detailed use cases. -Linux ```yml - name: Create Pull Request - uses: peter-evans/create-pull-request@v1.6.1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -``` - -Multi platform - Linux, MacOS, Windows (beta) -```yml - - name: Create Pull Request - uses: peter-evans/create-pull-request@v1.6.1-multi - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + uses: peter-evans/create-pull-request@v1.7.0 + with: + token: ${{ secrets.GITHUB_TOKEN }} ``` **Note**: If you want pull requests created by this action to trigger an `on: pull_request` workflow then you must use a [Personal Access Token](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) instead of the default `GITHUB_TOKEN`. See [this issue](https://github.com/peter-evans/create-pull-request/issues/48) for further details. -### Environment variables +### Action inputs -These variables are *all optional*. If not set, sensible default values will be used. +These inputs are *all optional*. If not set, sensible default values will be used. | Name | Description | Default | | --- | --- | --- | -| `COMMIT_MESSAGE` | The message to use when committing changes. | `Auto-committed changes by create-pull-request action` | -| `COMMIT_AUTHOR_EMAIL` | The email address of the commit author. | For `push` events, the HEAD commit author. Otherwise, @users.noreply.github.com, where `GITHUB_ACTOR` is the GitHub user that initiated the event. | -| `COMMIT_AUTHOR_NAME` | The name of the commit author. | For `push` events, the HEAD commit author. Otherwise, , the GitHub user that initiated the event. | -| `PULL_REQUEST_TITLE` | The title of the pull request. | `Auto-generated by create-pull-request action` | -| `PULL_REQUEST_BODY` | The body of the pull request. | `Auto-generated pull request by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub Action` | -| `PULL_REQUEST_LABELS` | A comma separated list of labels. | none | -| `PULL_REQUEST_ASSIGNEES` | A comma separated list of assignees (GitHub usernames). | none | -| `PULL_REQUEST_REVIEWERS` | A comma separated list of reviewers (GitHub usernames) to request a review from. | none | -| `PULL_REQUEST_TEAM_REVIEWERS` | A comma separated list of GitHub teams to request a review from. | none | -| `PULL_REQUEST_MILESTONE` | The number of the milestone to associate this pull request with. | none | -| `PULL_REQUEST_BRANCH` | The branch name. See **Branch naming** below for details. | `create-pull-request/patch` | -| `PULL_REQUEST_BASE` | Overrides the base branch. **Use with caution!** | Defaults to the currently checked out branch. | -| `BRANCH_SUFFIX` | The branch suffix type. Valid values are `short-commit-hash`, `timestamp`, `random` and `none`. See **Branch naming** below for details. | `short-commit-hash` | +| `commit-message` | The message to use when committing changes. | `Auto-committed changes by create-pull-request action` | +| `author-email` | The email address of the commit author. | For `push` events, the HEAD commit author. Otherwise, @users.noreply.github.com, where `GITHUB_ACTOR` is the GitHub user that initiated the event. | +| `author-name` | The name of the commit author. | For `push` events, the HEAD commit author. Otherwise, , the GitHub user that initiated the event. | +| `title` | The title of the pull request. | `Auto-generated by create-pull-request action` | +| `body` | The body of the pull request. | `Auto-generated pull request by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub Action` | +| `labels` | A comma separated list of labels. | none | +| `assignees` | A comma separated list of assignees (GitHub usernames). | none | +| `reviewers` | A comma separated list of reviewers (GitHub usernames) to request a review from. | none | +| `team-reviewers` | A comma separated list of GitHub teams to request a review from. | none | +| `milestone` | The number of the milestone to associate this pull request with. | none | +| `branch` | The branch name. See **Branch naming** below for details. | `create-pull-request/patch` | +| `base` | Overrides the base branch. **Use with caution!** | Defaults to the currently checked out branch. | +| `branch-suffix` | The branch suffix type. Valid values are `short-commit-hash`, `timestamp`, `random` and `none`. See **Branch naming** below for details. | `short-commit-hash` | -**Output environment variables** +**Outputs** -- `PULL_REQUEST_NUMBER` - The number of the pull request created. +The pull request number is output as both an environment variable and a step output. +Note that in order to read the step output the action step must have an id. -**Debug environment variables** - -The following parameter is available for debugging and troubleshooting. - -- `DEBUG_EVENT` - If present, outputs the event data that triggered the workflow. +```yml + - name: Create Pull Request + id: cpr + uses: peter-evans/create-pull-request@v1.7.0 + with: + token: ${{ secrets.GITHUB_TOKEN }} + - name: Check outputs + run: | + echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}" + echo "Pull Request Number - ${{ steps.cpr.outputs.pr_number }}" +``` ### Branch naming @@ -73,7 +71,7 @@ For branch naming there are two strategies. Always create a new branch each time #### Strategy A - Always create a new pull request branch (default) For this strategy there are three options to suffix the branch name. -The branch name is defined by the variable `PULL_REQUEST_BRANCH` and defaults to `create-pull-request/patch`. The following options are values for `BRANCH_SUFFIX`. +The branch name is defined by the input `branch` and defaults to `create-pull-request/patch`. The following options are values for `branch-suffix`. - `short-commit-hash` (default) - Commits will be made to a branch suffixed with the short SHA1 commit hash. e.g. `create-pull-request/patch-fcdfb59`, `create-pull-request/patch-394710b` @@ -83,7 +81,7 @@ The branch name is defined by the variable `PULL_REQUEST_BRANCH` and defaults to #### Strategy B - Create and update a pull request branch -To use this strategy, set `BRANCH_SUFFIX` to the value `none`. The variable `PULL_REQUEST_BRANCH` defaults to `create-pull-request/patch`. Commits will be made to this branch and a pull request created. Any subsequent changes will be committed to the *same* branch and reflected in the existing pull request. +To use this strategy, set `branch-suffix` to the value `none`. The input `branch` defaults to `create-pull-request/patch`. Commits will be made to this branch and a pull request created. Any subsequent changes will be committed to the *same* branch and reflected in the existing pull request. ### Ignoring files @@ -91,7 +89,7 @@ If there are files or directories you want to ignore you can simply add them to ## Reference Example -The following workflow is a reference example that sets all the main environment variables. +The following workflow is a reference example that sets all the main inputs. See [examples](examples.md) for more realistic use cases. @@ -106,27 +104,30 @@ jobs: - name: Create report file run: date +%s > report.txt - name: Create Pull Request - uses: peter-evans/create-pull-request@v1.6.1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - COMMIT_MESSAGE: Add report file - COMMIT_AUTHOR_EMAIL: peter-evans@users.noreply.github.com - COMMIT_AUTHOR_NAME: Peter Evans - PULL_REQUEST_TITLE: '[Example] Add report file' - PULL_REQUEST_BODY: | + id: cpr + uses: peter-evans/create-pull-request@v1.7.0 + with: + token: ${{ secrets.GITHUB_TOKEN }} + commit-message: Add report file + author-email: peter-evans@users.noreply.github.com + author-name: Peter Evans + title: '[Example] Add report file' + body: | New report - Contains *today's* date - Auto-generated by [create-pull-request][1] [1]: https://github.com/peter-evans/create-pull-request - PULL_REQUEST_LABELS: report, automated pr - PULL_REQUEST_ASSIGNEES: peter-evans - PULL_REQUEST_REVIEWERS: peter-evans - PULL_REQUEST_MILESTONE: 1 - PULL_REQUEST_BRANCH: example-patches - BRANCH_SUFFIX: short-commit-hash - - name: Check output environment variable - run: echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}" + labels: report, automated pr + assignees: peter-evans + reviewers: peter-evans + milestone: 1 + branch: example-patches + branch-suffix: short-commit-hash + - name: Check outputs + run: | + echo "Pull Request Number - ${{ env.PULL_REQUEST_NUMBER }}" + echo "Pull Request Number - ${{ steps.cpr.outputs.pr_number }}" ``` This reference configuration will create pull requests that look like this: