Merge branch 'main' into add-labels-feature

github · Apr 3, 2023 · d627eb3 · d627eb3
2 parents 26ed058 + fda8056
commit d627eb3
Show file tree

Hide file tree

Showing 7 changed files with 103 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -109,40 +109,8 @@ If you need CI to re-run on your newly created "combined" PR, you'll need to use
     github_token: ${{ secrets.PAT }} # where PAT is a GitHub Action's secret containing a personal access token
 ```
 
-Alternatively, you can use a GitHub App token. This is the recommended approach as it is more secure than a personal access token and a lot more scalable for large organizations. The following open source [Action](https://github.com/marketplace/actions/use-app-token) helps to generate a GitHub App token for you which can then be passed into the `combine-prs` Action.
+### GitHub App Setup
 
-Here is an example doing exactly that:
+Alternatively, you can use a GitHub App token. This is the recommended approach as it is more secure than a personal access token and a lot more scalable for large organizations.
 
-```yaml
-name: Combine PRs
-
-on:
-  schedule:
-    - cron: '0 1 * * 3' # Wednesday at 01:00
-  workflow_dispatch:
-
-jobs:
-  combine-prs:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Use GitHub App Token
-        uses: wow-actions/use-app-token@d7957e08172ca2e8e49b35b8d266ad585885edc7 # pin@v2.0.2
-        id: generate_token
-        with:
-          app_id: ${{ secrets.APP_ID }} # The ID of the GitHub App
-          private_key: ${{ secrets.PRIVATE_KEY }} # The private key of the GitHub App
-          fallback: ${{ secrets.GITHUB_TOKEN }} # fall back to the default token if the app token is not available
-
-      - name: combine-prs
-        uses: github/combine-prs@vX.X.X # where X.X.X is the latest version
-        with:
-          github_token: ${{ steps.generate_token.outputs.BOT_TOKEN }} # A GitHub app token generated by the previous step
-```
-
-If you go the GitHub App route, it will need the following permissions for your GitHub App:
-
-- Commit statuses: `Read-only`
-- Contents: `Read and write`
-- Metadata: `Read-only`
-- Pull requests: `Read and write`
+Checkout the dedicated [documentation here](docs/github-app-setup.md) for more information on how to set this up.
diff --git a/docs/assets/new-github-app-1.png b/docs/assets/new-github-app-1.png
diff --git a/docs/assets/new-github-app-2.png b/docs/assets/new-github-app-2.png
diff --git a/docs/assets/new-github-app-3.png b/docs/assets/new-github-app-3.png
diff --git a/docs/assets/new-github-app-4.png b/docs/assets/new-github-app-4.png
diff --git a/docs/assets/new-github-app-5.png b/docs/assets/new-github-app-5.png
diff --git a/docs/github-app-setup.md b/docs/github-app-setup.md
@@ -0,0 +1,100 @@
+# GitHub App Setup
+
+This section goes into detail on how to use a [GitHub App](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps) to generate a token that can be used to run the `combine-prs` Action.
+
+## Why use a GitHub App?
+
+GitHub Apps are more scalable than personal access tokens. They can be installed on multiple repositories and can be used by multiple users. They also have a higher rate limit than personal access tokens. If you are an enterprise user, or organization with a lot of repositories, you *should* use a GitHub App instead of a personal access token.
+
+## Setting up a GitHub App
+
+Before we can write up the `combine-prs` Action, we need to create a GitHub App. You can do this by going to `Settings` > `Developer settings` > `GitHub Apps` > `New GitHub App`.
+
+Follow along with the screenshots below to create a new GitHub App:
+
+![new-github-app-1](assets/new-github-app-1.png)
+
+Enter a unique name for your GitHub App, a meaningful description, and any link you want. Ensure you expire user authorization tokens.
+
+![new-github-app-2](assets/new-github-app-2.png)
+
+Keep all the defaults in the next section as indicated by the screenshot. The only thing you will want to do in this section is disable the `Webhook` option. Ensure `Active` is "unchecked".
+
+![new-github-app-3](assets/new-github-app-3.png)
+
+In this section, you will want to enable the following repository permissions:
+
+- Commit statuses: `Read-only`
+- Contents: `Read and write`
+- Metadata: `Read-only`
+- Pull requests: `Read and write`
+
+Also ensure that you select `Only on this account` for the installation option
+
+Now you can go ahead and create your GitHub App!
+
+## Configuring Secrets
+
+In order for your `combine-prs` Action workflow to properly run, you will need to configure two secrets for your workflow using credentials from the GitHub App you just created.
+
+### `APP_ID`
+
+You can find your applications ID on the `General` page of your GitHub App. It will be listed as `App ID`.
+
+![new-github-app-4](assets/new-github-app-4.png)
+
+Make note of your `APP_ID` as we will use it shortly
+
+### `PRIVATE_KEY`
+
+You will now need to generate a private key for your GitHub App. This section will also be located on the `General` page of your GitHub App.
+
+![new-github-app-5](assets/new-github-app-5.png)
+
+> Note: When you generate a private key, it will download a `.pem` file. You will need to copy the contents of this file and paste it into your secret.
+
+Make note of your `PRIVATE_KEY` as we will use it shortly
+
+### Setting Secrets
+
+Now that you have the values of both your `APP_ID` and `PRIVATE_KEY`, you can go ahead and set them as secrets in your repository. Where you wish to run the `combine-prs` Action, go to `Settings` > `Secrets` > `New repository secret`. Create the following two secrets:
+
+- `APP_ID`: The ID of your GitHub App
+- `PRIVATE_KEY`: The private key of your GitHub App
+
+> Note: You can also set these secrets at the organization level if you wish to run the `combine-prs` Action across multiple repositories.
+
+## Setting up the `combine-prs` Action
+
+Now that the GitHub App is set up and the secrets are configured, we can go ahead and set up the `combine-prs` Action. *Finally*!
+
+The following open source [Action](https://github.com/marketplace/actions/use-app-token) helps to generate a GitHub App token for you which can then be passed into the `combine-prs` Action.
+
+Here is the example workflow that you can use to run the `combine-prs` Action with a GitHub App:
+
+```yaml
+name: Combine PRs
+
+on:
+  schedule:
+    - cron: '0 1 * * 3' # Wednesday at 01:00
+  workflow_dispatch:
+
+jobs:
+  combine-prs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Use GitHub App Token
+        uses: wow-actions/use-app-token@d7957e08172ca2e8e49b35b8d266ad585885edc7 # pin@v2.0.2
+        id: generate_token
+        with:
+          app_id: ${{ secrets.APP_ID }} # The ID of the GitHub App
+          private_key: ${{ secrets.PRIVATE_KEY }} # The private key of the GitHub App
+          fallback: ${{ secrets.GITHUB_TOKEN }} # fall back to the default token if the app token is not available
+
+      - name: combine-prs
+        uses: github/combine-prs@vX.X.X # where X.X.X is the latest version
+        with:
+          github_token: ${{ steps.generate_token.outputs.BOT_TOKEN }} # A GitHub app token generated by the previous step
+```