From 3f7ad828a403e6de8268ae53d34f8c9837faa655 Mon Sep 17 00:00:00 2001 From: Gregor Martynus <39992+gr2m@users.noreply.github.com> Date: Thu, 18 May 2023 17:38:04 -0700 Subject: [PATCH 1/4] WIP readme additions --- README.md | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 232b17af..ebbcc6b1 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ In order to use this action, you need to -1. [Register new GitHub App](#TBD) -2. [Store the App's ID in your repository environment variables](#TBD) -3. [Store the App's private key in your repository secrets](#TBD) +1. GitHub App Credentials (ID and private key) ([Register new GitHub App](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)) +2. [Store the App's ID in your repository environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows) +3. [Store the App's private key in your repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets?tool=webui#creating-encrypted-secrets-for-a-repository) ### Minimal usage @@ -49,7 +49,8 @@ jobs: # optional: set permissions (#TBD) permissions_contents: write # optional: set repositories - repositories: gr2m/my-repo1,gr2m/my-repo2 + account: gr2m + repositories: my-repo1,my-repo2 # do something with the token ``` @@ -81,9 +82,20 @@ jobs: ## How it works -TBD +The action creates an installation access token using [the `POST /app/installations/{installation_id}/access_tokens` endpoint](https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app). By default, -- [ ] Find out if the created token can be revoked in the post step of the action +1. The token is scoped to the current repository +2. The token inherits all of the installations permissions +3. The token is set as output `token` which can be used in subsequent steps +4. The token is revoked in the `post` step of the action, which means it cannot be passed to another job. Set `revoke: false` to disable revoking +5. The token is masked, it cannot be logged accidentally. That is not a feature by the action, but by the GitHub Actions runner itself, due to the specific format of GitHub tokens. + +> **Note** +> Installation permissions can differ from the app's permissions they belong to. Installation permissions are set when an app is installed on an account. When the app adds more permissions after the installation, an account administrator will have to approve the new permissions before they are set on the installation. + +It is considered best practice to only request the permissions that are needed. You can define a subset of permissions using the `permissions_*` inputs. For example, if you only need to read the contents of a repository, you can set `permissions_contents: read`. If you need to read and write, you can set `permissions_contents: write`. You can only define permissions that are a subset of the respective installation's permissions. + +You can grant access to the token to multiple repositories using the `account` and `repositories` inputs. For example, if you want to grant access to all repositories of the `gr2m` account, you can set `account: gr2m`. If you want to grant access to specific repositories, you can set `account: gr2m` and `repositories: repo1,repo2`. Unfortunately it is not possible to create a single token that has access across multiple accounts, as different accounts have different installations. You will have to call `gr2m/app-token-action` once per account instead. ## License From 96a71193fe30b61923df253d9f0b83f0530b684d Mon Sep 17 00:00:00 2001 From: Gregor Martynus <39992+gr2m@users.noreply.github.com> Date: Thu, 18 May 2023 22:06:41 -0700 Subject: [PATCH 2/4] Update README.md Co-authored-by: Parker Brown <17183625+parkerbxyz@users.noreply.github.com> --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ebbcc6b1..de8b5839 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ In order to use this action, you need to -1. GitHub App Credentials (ID and private key) ([Register new GitHub App](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)) -2. [Store the App's ID in your repository environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows) -3. [Store the App's private key in your repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets?tool=webui#creating-encrypted-secrets-for-a-repository) +1. GitHub App Credentials (ID and private key) ([Register new GitHub App](https://docs.github.com/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)) +2. [Store the App's ID in your repository environment variables](https://docs.github.com/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows) +3. [Store the App's private key in your repository secrets](https://docs.github.com/actions/security-guides/encrypted-secrets?tool=webui#creating-encrypted-secrets-for-a-repository) ### Minimal usage From a317118ffbbc6e60e087f78eb68adb36f02e5b02 Mon Sep 17 00:00:00 2001 From: Gregor Martynus <39992+gr2m@users.noreply.github.com> Date: Thu, 18 May 2023 22:07:16 -0700 Subject: [PATCH 3/4] Update README.md Co-authored-by: Parker Brown <17183625+parkerbxyz@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de8b5839..7568ee49 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ jobs: # optional: set permissions (#TBD) permissions_contents: write # optional: set repositories - account: gr2m + owner: gr2m repositories: my-repo1,my-repo2 # do something with the token ``` From 7c924ebf4a79995833f11237923a66563c8d13ab Mon Sep 17 00:00:00 2001 From: Gregor Martynus <39992+gr2m@users.noreply.github.com> Date: Thu, 18 May 2023 22:07:28 -0700 Subject: [PATCH 4/4] Update README.md Co-authored-by: Parker Brown <17183625+parkerbxyz@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 7568ee49..105e6f5b 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ jobs: ## How it works -The action creates an installation access token using [the `POST /app/installations/{installation_id}/access_tokens` endpoint](https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app). By default, +The action creates an installation access token using [the `POST /app/installations/{installation_id}/access_tokens` endpoint](https://docs.github.com/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app). By default, 1. The token is scoped to the current repository 2. The token inherits all of the installations permissions