You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Improve the README.md documentation of how to create a GitHub App
After struggling twice through creating a GitHub App, I filed actions#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?
Copy file name to clipboardExpand all lines: README.md
+14-5
Original file line number
Diff line number
Diff line change
@@ -6,11 +6,20 @@ GitHub Action for creating a GitHub App installation access token.
6
6
7
7
## Usage
8
8
9
-
In order to use this action, you need to:
10
-
11
-
1.[Register new GitHub App](https://docs.github.com/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)
12
-
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`)
13
-
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`)
9
+
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.
10
+
11
+
[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:
12
+
-[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)
13
+
-[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)
14
+
- Here are the requirements if you manually create the app:
15
+
1. Uncheck `Webhook` > `Active` checkbox
16
+
2. Mark two permissions under `Repository permissions` as read-only: `Contents` and `Metadata`
17
+
18
+
Once you have the GitHub app installed, there are a few manual steps you must follow to finish setup:
19
+
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.
20
+
2. In the `Install app` section of your newly-created app, choose the organizations that you want to install your application into.
21
+
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`)
22
+
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`)
0 commit comments