From 77fb4638847c44d4efbb2aa33ebb476b4c94f484 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vin=C3=ADcius=20Vargas?= Date: Mon, 10 Oct 2022 05:37:25 -0300 Subject: [PATCH 1/6] Fix: Information related to tokens in README Fix documentation related to tokens. The secrets.GITHUB_TOKEN provided by the GitHub Actions App can do everything related to the repo if we elevate its permissions, including calling workflow_dispatch and repository_dispatch. Some people in my organization are using PAT's instead of the secrets.GITHUB_TOKEN when using this action because of this README suggestion, even when they are calling the same repository. Using PATs in that contexts provides unnecessary security risks. --- README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 9c86df0..1374303 100644 --- a/README.md +++ b/README.md @@ -18,15 +18,22 @@ A GitHub action to create a repository dispatch event. | Name | Description | Default | | --- | --- | --- | -| `token` | (**required**) A `repo` scoped GitHub [Personal Access Token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token). See [token](#token) for further details. | | +| `token` | (**required**) A GitHub access token with `actions: write` permission to the repository being dispatched. | | | `repository` | The full name of the repository to send the dispatch. | `github.repository` (current repository) | | `event-type` | (**required**) A custom webhook event name. | | | `client-payload` | JSON payload with extra information about the webhook event that your action or workflow may use. | `{}` | #### `token` -This action creates [`repository_dispatch`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. -The default `GITHUB_TOKEN` does not have scopes to do this so a `repo` scoped [PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) created on a user with `write` access to the target repository is required. +This action creates [`repository_dispatch`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. The default `GITHUB_TOKEN` +token can only be used if you are dispatching the same repo. In this case you must assign the permission `action: write` to the token, see [permissions api](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs). Example: +```yaml +permissions: + actions: write +``` + +The solution to trigger other repositories is to manually create a PAT and store it as a secret e.g. `${{ secrets.PERSONAL_TOKEN }}`. + If you will be dispatching to a public repository then you can use the more limited `public_repo` scope. ## Example From 3c4e552d1053f3fce9b9acaa7e493a51a058abaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vin=C3=ADcius=20Vargas?= Date: Mon, 10 Oct 2022 05:38:56 -0300 Subject: [PATCH 2/6] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1374303..ce58fb1 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ permissions: actions: write ``` -The solution to trigger other repositories is to manually create a PAT and store it as a secret e.g. `${{ secrets.PERSONAL_TOKEN }}`. +The solution to trigger other repositories is to manually create a [PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and store it as a secret e.g. `${{ secrets.PERSONAL_TOKEN }}`. If you will be dispatching to a public repository then you can use the more limited `public_repo` scope. From b700ade2f3efd0052e63446b4fa78779609c75b5 Mon Sep 17 00:00:00 2001 From: Peter Evans <18365890+peter-evans@users.noreply.github.com> Date: Wed, 19 Oct 2022 16:27:30 +0900 Subject: [PATCH 3/6] Update ci to use default token --- .github/workflows/ci.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6d669dd..b66989a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,6 +14,7 @@ on: permissions: pull-requests: write contents: write + actions: write jobs: build: @@ -60,14 +61,12 @@ jobs: - name: Test repository dispatch uses: ./ with: - token: ${{ secrets.REPO_ACCESS_TOKEN }} event-type: tests client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}' - name: Test repository dispatch (default payload) uses: ./ with: - token: ${{ secrets.REPO_ACCESS_TOKEN }} event-type: tests package: From aebc1699294261773e6b5a52e98dde0990d5ce1b Mon Sep 17 00:00:00 2001 From: Peter Evans <18365890+peter-evans@users.noreply.github.com> Date: Wed, 19 Oct 2022 16:27:58 +0900 Subject: [PATCH 4/6] Update action config to set a default token --- action.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/action.yml b/action.yml index 95ab44e..a68a086 100644 --- a/action.yml +++ b/action.yml @@ -2,8 +2,8 @@ name: 'Repository Dispatch' description: 'Create a repository dispatch event' inputs: token: - description: 'A repo scoped GitHub Personal Access Token' - required: true + description: 'GITHUB_TOKEN or a `repo` scoped Personal Access Token (PAT)' + default: ${{ github.token }} repository: description: 'The full name of the repository to send the dispatch.' default: ${{ github.repository }} From 66463e47e79dfbd0d57eeaf82b5a3d42c4b223ec Mon Sep 17 00:00:00 2001 From: Peter Evans <18365890+peter-evans@users.noreply.github.com> Date: Wed, 19 Oct 2022 16:28:06 +0900 Subject: [PATCH 5/6] Update docs --- README.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ce58fb1..4c7f6cb 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,22 @@ A GitHub action to create a repository dispatch event. ## Usage +Dispatch to the current repository by elivating the permissions of the default `GITHUB_TOKEN`. +```yml +permissions: + actions: write + +jobs: + repositorydispatch: + runs-on: ubuntu-latest + steps: + - name: Repository Dispatch + uses: peter-evans/repository-dispatch@v2 + with: + event-type: my-event +``` + +Dispatch to a remote repository using a `repo` scoped GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). ```yml - name: Repository Dispatch uses: peter-evans/repository-dispatch@v2 @@ -18,22 +34,23 @@ A GitHub action to create a repository dispatch event. | Name | Description | Default | | --- | --- | --- | -| `token` | (**required**) A GitHub access token with `actions: write` permission to the repository being dispatched. | | +| `token` | (**required**) `GITHUB_TOKEN` (permissions `actions: write`) or a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). See [token](#token) for further details. | `GITHUB_TOKEN` | | `repository` | The full name of the repository to send the dispatch. | `github.repository` (current repository) | | `event-type` | (**required**) A custom webhook event name. | | | `client-payload` | JSON payload with extra information about the webhook event that your action or workflow may use. | `{}` | #### `token` -This action creates [`repository_dispatch`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. The default `GITHUB_TOKEN` -token can only be used if you are dispatching the same repo. In this case you must assign the permission `action: write` to the token, see [permissions api](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs). Example: +This action creates [`repository_dispatch`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. +The default `GITHUB_TOKEN` token can only be used if you are dispatching the same repository that the workflow is executing in. +In this case you must [elevate the token permissions](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) to allow the dispatch. + ```yaml permissions: actions: write ``` -The solution to trigger other repositories is to manually create a [PAT](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and store it as a secret e.g. `${{ secrets.PERSONAL_TOKEN }}`. - +To dispatch to a remote repository you must create a [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with the `repo` scope and store it as a secret. If you will be dispatching to a public repository then you can use the more limited `public_repo` scope. ## Example From 2f6d32ce8360a441d6c48af854a92377ca908c71 Mon Sep 17 00:00:00 2001 From: Peter Evans <18365890+peter-evans@users.noreply.github.com> Date: Wed, 19 Oct 2022 16:34:26 +0900 Subject: [PATCH 6/6] Update docs --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4c7f6cb..45e5470 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ A GitHub action to create a repository dispatch event. ## Usage -Dispatch to the current repository by elivating the permissions of the default `GITHUB_TOKEN`. +Dispatch an event to the current repository by elivating the permissions of the default `GITHUB_TOKEN`. ```yml permissions: actions: write @@ -21,7 +21,7 @@ jobs: event-type: my-event ``` -Dispatch to a remote repository using a `repo` scoped GitHub [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). +Dispatch an event to a remote repository using a `repo` scoped [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token). ```yml - name: Repository Dispatch uses: peter-evans/repository-dispatch@v2 @@ -39,9 +39,9 @@ Dispatch to a remote repository using a `repo` scoped GitHub [Personal Access To | `event-type` | (**required**) A custom webhook event name. | | | `client-payload` | JSON payload with extra information about the webhook event that your action or workflow may use. | `{}` | -#### `token` +#### Token -This action creates [`repository_dispatch`](https://developer.github.com/v3/repos/#create-a-repository-dispatch-event) events. +This action creates [`repository_dispatch`](https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event) events. The default `GITHUB_TOKEN` token can only be used if you are dispatching the same repository that the workflow is executing in. In this case you must [elevate the token permissions](https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs) to allow the dispatch.