Skip to content

Commit

Permalink
Improve the README.md documentation of how to create a GitHub App
Browse files Browse the repository at this point in the history
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?
  • Loading branch information
grossag committed Dec 27, 2023
1 parent 2986852 commit 58c1ffb
Showing 1 changed file with 14 additions and 5 deletions.
19 changes: 14 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 58c1ffb

Please sign in to comment.