From 58c1ffbd7d8fca2ff64b9a9fea7687219d45e533 Mon Sep 17 00:00:00 2001 From: Adam Gross Date: Wed, 27 Dec 2023 06:19:57 -0600 Subject: [PATCH 1/2] Improve the README.md documentation of how to create a GitHub App After struggling twice through creating a GitHub App, I filed https://github.com/actions/create-github-app-token/issues/89 and was encouraged to submit a pull request. This patch attempts to improve the documentation by: 1. Documenting the requirements for the GitHub app. 2. Providing URLs to make app creation easier like GitHub ARC docs do. I am not certain whether everything I added is correct, so please take a look and confirm. Parts I am unsure of: 1. Is there any use case where users will want to create this app in their account, not in an organization? I included a link to cover that case, but I am not sure if it is necessary. 2. Is there any other customization I need to include in the URL query params? 3. Are the manual requirements I included correct? --- README.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0e3bc2b..ac06b2b 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,20 @@ GitHub Action for creating a GitHub App installation access token. ## Usage -In order to use this action, you need to: - -1. [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) (example: `APP_ID`) -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) (example: `PRIVATE_KEY`) +In order to use this action, you must first create a GitHub App. This is required in order to give create-github-app-token the necessary permissions to be able to generate tokens. + +[See this page](https://docs.github.com/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) for more details on how to register a GitHub App. Here are ways that you can create the app: +- [Use this link to create the GitHub app in your account](https://github.com/settings/apps/new?url=https://github.com/actions/create-github-app-token&webhook_active=false&public=false&contents=read&metadata=read) +- [Use this link to create the GitHub app in your organization](https://github.com/organizations/:org/settings/apps/new?url=https://github.com/actions/create-github-app-token&webhook_active=false&public=false&contents=read&metadata=read) (note: link will be dead and you must replace `:org` with your organization name) +- Here are the requirements if you manually create the app: + 1. Uncheck `Webhook` > `Active` checkbox + 2. Mark two permissions under `Repository permissions` as read-only: `Contents` and `Metadata` + +Once you have the GitHub app installed, there are a few manual steps you must follow to finish setup: +1. In the `Private keys` section of your newly-created app, click `Generate a private key`. This will automatically trigger your web browser to download the private key .pem file, which will be used in step 4. +2. In the `Install app` section of your newly-created app, choose the organizations that you want to install your application into. +3. [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) (example: `APP_ID`) +4. [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) (example: `PRIVATE_KEY`) ### Create a token for the current repository From 5048a2d273bab54714c3b8ec4d48baa7331d410a Mon Sep 17 00:00:00 2001 From: Adam Gross Date: Fri, 1 Mar 2024 14:01:13 -0500 Subject: [PATCH 2/2] Some wording changes It could use some more examples of permissions, but it's a start. --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 7aa4f11..968e36a 100644 --- a/README.md +++ b/README.md @@ -9,15 +9,15 @@ GitHub Action for creating a GitHub App installation access token. In order to use this action, you must first create a GitHub App. This is required in order to give create-github-app-token the necessary permissions to be able to generate tokens. [See this page](https://docs.github.com/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app) for more details on how to register a GitHub App. Here are ways that you can create the app: -- [Use this link to create the GitHub app in your account](https://github.com/settings/apps/new?url=https://github.com/actions/create-github-app-token&webhook_active=false&public=false&contents=read&metadata=read) -- [Use this link to create the GitHub app in your organization](https://github.com/organizations/:org/settings/apps/new?url=https://github.com/actions/create-github-app-token&webhook_active=false&public=false&contents=read&metadata=read) (note: link will be dead and you must replace `:org` with your organization name) -- Here are the requirements if you manually create the app: - 1. Uncheck `Webhook` > `Active` checkbox - 2. Mark two permissions under `Repository permissions` as read-only: `Contents` and `Metadata` +- [Use this link to create the GitHub app in your account](https://github.com/settings/apps/new?url=https://github.com/actions/create-github-app-token&webhook_active=false&public=false&metadata=read) +- [Use this link to create the GitHub app in your organization](https://github.com/organizations/:org/settings/apps/new?url=https://github.com/actions/create-github-app-token&webhook_active=false&public=false&metadata=read) (note: link will be dead and you must replace `:org` with your organization name) + +The permissions that you give to the application depend on your use case: +- If you will use app tokens with `actions/checkout` to check out a private or internal repository (as described below), you will want to mark at least one permission under `Repository permissions` as read-only: `Contents` Once you have the GitHub app installed, there are a few manual steps you must follow to finish setup: 1. In the `Private keys` section of your newly-created app, click `Generate a private key`. This will automatically trigger your web browser to download the private key .pem file, which will be used in step 4. -2. In the `Install app` section of your newly-created app, choose the organizations that you want to install your application into. +2. In the `Install app` section of your newly-created app, choose where you want to install the application. If installing into an Enterprise account, you would choose the organization(s) that you want to install your application into. 3. [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) (example: `APP_ID`) 4. [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) (example: `PRIVATE_KEY`)