Add missing inputs to action.yml, refactor auth docs (#163)

* Update action.yml * Update golangci-lint installation process * Update docs
mszostok · Jul 7, 2022 · ccda6cc · ccda6cc
1 parent 55fa530
commit ccda6cc
Show file tree

Hide file tree

Showing 7 changed files with 106 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -121,10 +121,10 @@ Use the following environment variables to configure the application:
 | Name                                          | Default                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 |-----------------------------------------------|:------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | <tt>REPOSITORY_PATH</tt> <b>*</b>             |                               | Path to your repository on your local machine.                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| <tt>GITHUB_ACCESS_TOKEN</tt>                  |                               | GitHub access token. Instruction for creating a token can be found [here](./docs/gh-token.md). If not provided, the owners validating functionality may not work properly. For example, you may reach the API calls quota or, if you are setting GitHub Enterprise base URL, an unauthorized error may occur.                                                                                                                                                   |
+| <tt>GITHUB_ACCESS_TOKEN</tt>                  |                               | GitHub access token. Instruction for creating a token can be found [here](./docs/gh-auth.md). If not provided, the owners validating functionality may not work properly. For example, you may reach the API calls quota or, if you are setting GitHub Enterprise base URL, an unauthorized error may occur.                                                                                                                                                   |
 | <tt>GITHUB_BASE_URL</tt>                      | `https://api.github.com/`     | GitHub base URL for API requests. Defaults to the public GitHub API but can be set to a domain endpoint to use with GitHub Enterprise.                                                                                                                                                                                                                                                                                                                          |
 | <tt>GITHUB_UPLOAD_URL</tt>                    | `https://uploads.github.com/` | GitHub upload URL for uploading files. <br> <br>It is taken into account only when `GITHUB_BASE_URL` is also set. If only `GITHUB_BASE_URL` is provided, this parameter defaults to the `GITHUB_BASE_URL` value.                                                                                                                                                                                                                                                |
-| <tt>GITHUB_APP_ID</tt>                        |                               | Github App ID for authentication. This replaces the `GITHUB_ACCESS_TOKEN`. Instruction for creating a Github App can be found [here](./docs/gh-token.md)                                                                                                                                                                                                                                                                                                        |
+| <tt>GITHUB_APP_ID</tt>                        |                               | Github App ID for authentication. This replaces the `GITHUB_ACCESS_TOKEN`. Instruction for creating a Github App can be found [here](./docs/gh-auth.md)                                                                                                                                                                                                                                                                                                        |
 | <tt>GITHUB_APP_INSTALLATION_ID</tt>           |                               | Github App Installation ID. Required when `GITHUB_APP_ID` is set.                                                                                                                                                                                                                                                                                                                                                                                               |
 | <tt>GITHUB_APP_PRIVATE_KEY</tt>               |                               | Github App private key in PEM format. Required when `GITHUB_APP_ID` is set.                                                                                                                                                                                                                                                                                                                                                                                     |
 | <tt>CHECKS</tt>                               |                               | List of checks to be executed. By default, all checks are executed. Possible values: `files`,`owners`,`duppatterns`,`syntax`.                                                                                                                                                                                                                                                                                                                                   |

diff --git a/action.yml b/action.yml
@@ -7,6 +7,18 @@ inputs:
     description: "The GitHub access token. Instruction for creating a token can be found here: https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token. If not provided then validating owners functionality could not work properly, e.g. you can reach the API calls quota or if you are setting GitHub Enterprise base URL then an unauthorized error can occur."
     required: false
 
+  github_app_id:
+    description: "Github App ID for authentication. This replaces the GITHUB_ACCESS_TOKEN. Instruction for creating a Github App can be found here: https://github.com/mszostok/codeowners-validator/blob/main/docs/gh-token.md"
+    required: false
+
+  github_app_installation_id:
+    description: "Github App Installation ID. Required when GITHUB_APP_ID is set."
+    required: false
+
+  github_app_private_key:
+    description: "Github App private key in PEM format. Required when GITHUB_APP_ID is set."
+    required: false
+
   github_base_url:
     description: "The GitHub base URL for API requests. Defaults to the public GitHub API, but can be set to a domain endpoint to use with GitHub Enterprise. Default: https://api.github.com/"
     required: false

diff --git a/docs/README.md b/docs/README.md
@@ -7,5 +7,5 @@ Welcome to the Codeowners Validator documentation.
 
 + [Development](./development.md)
 + [GitHub Action](./gh-action.md)
-+ [GitHub personal access token](./gh-token.md)
++ [GitHub Auth](./gh-auth.md)
 + [Release](./release.md)
diff --git a/docs/gh-action.md b/docs/gh-action.md
@@ -38,15 +38,30 @@ jobs:
         uses: mszostok/[email protected]
         # input parameters
         with:
-          # "The list of checks that will be executed. By default, all checks are executed. Possible values: files,owners,duppatterns,syntax"
-          checks: "files,owners,duppatterns,syntax"
-
-          # "The comma-separated list of experimental checks that should be executed. By default, all experimental checks are turned off. Possible values: notowned."
-          experimental_checks: "notowned"
+          # ==== GitHub Auth ====
 
+          ## ==== PAT ====
           # GitHub access token is required only if the `owners` check is enabled
           github_access_token: "${{ secrets.OWNERS_VALIDATOR_GITHUB_SECRET }}"
 
+          ## ==== App ====
+          # GitHub App ID for authentication. This replaces the github_access_token.
+          github_app_id: ${{ secrets.APP_ID }}
+
+          # GitHub App Installation ID. Required when github_app_id is set.
+          github_app_installation_id: ${{ secrets.APP_INSTALLATION_ID }}
+
+          # GitHub App private key in PEM format. Required when github_app_id is set.
+          github_app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
+
+          # ==== GitHub Auth ====
+
+          # "The list of checks that will be executed. By default, all checks are executed. Possible values: files,owners,duppatterns,syntax"
+          checks: "files,owners,duppatterns,syntax"
+
+          # "The comma-separated list of experimental checks that should be executed. By default, all experimental checks are turned off. Possible values: notowned,avoid-shadowing"
+          experimental_checks: "notowned,avoid-shadowing"
+
           # The GitHub base URL for API requests. Defaults to the public GitHub API, but can be set to a domain endpoint to use with GitHub Enterprise.
           github_base_url: "https://api.github.com/"
 
@@ -80,7 +95,9 @@ jobs:
 
 The best is to run this as a cron job and not only if you applying changes to CODEOWNERS file itself, e.g. the CODEOWNERS file can be invalidate when you removing someone from the organization.
 
-> **Note**: To execute `owners` check you need to create a [GitHub token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token) and store it as a secret in your repository, see ["Creating and storing encrypted secrets."](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). Token requires only read-only scope for your repository.
+> **Note**
+>
+> To execute `owners` check you need to create a [GitHub token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token) and store it as a secret in your repository, see ["Creating and storing encrypted secrets."](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets). Token requires only read-only scope for your repository.
 
 <!--- example repository when failed -->
 

diff --git a/docs/gh-auth.md b/docs/gh-auth.md
@@ -0,0 +1,66 @@
+[← back to docs](./README.md)
+
+# GitHub tokens
+
+The [valid_owner.go](./../internal/check/valid_owner.go) check requires the GitHub token for the following reasons:
+
+1. Information about organization teams and their repositories is not publicly available.
+2. If you set GitHub Enterprise base URL, an unauthorized error may occur.
+3. For unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address. In a big organization where you have a lot of calls between your infrastructure server and the GitHub site, it is easy to exceed that quota.
+
+The Codeowners Validator source code is available on GitHub. You can always perform a security audit against its code base and build your own version from the source code if your organization is stricter about the software run in its infrastructure.
+
+You can either use a [personal access token](#github-personal-access-token) or a [GitHub App](#github-app).
+
+## GitHub personal access token
+
+Instructions for creating a token can be found [here](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token). The minimal scope required for the token is **read-only**, but the definition of this scope differs between public and private repositories.
+
+#### Public repositories
+
+For public repositories, select `public_repo` and `read:org`:
+
+![token-public.png](./assets/token-public.png)
+
+#### Private repositories
+
+For private repositories, select `repo` and `read:org`:
+
+![token-public.png](./assets/token-private.png)
+
+
+## GitHub App
+
+Here are the steps to create a GitHub App and use it for this tool:
+
+1. [Create a GitHub App](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app).
+    > **Note**
+    > Your app does not need a callback or a webhook URL.
+2. Add a read-only permission to the "Members" item of organization permissions.
+3. [Install the app in your organization](https://docs.github.com/en/developers/apps/managing-github-apps/installing-github-apps).
+4. Done! To authenticate with your app, you need:
+
+    | Name                       | Description                                                                                                                                                                                                                                       |
+    |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+    | GitHub App Private Key     | PEM-format key generated when the app is installed. If you lost it, you can regenerate it ([docs](https://docs.github.com/en/developers/apps/building-github-apps/authenticating-with-github-apps#generating-a-private-key)).                     |
+    | GitHub App ID              | Found in the app's "About" page (Organization settings -> Developer settings -> Edit button on your app).                                                                                                                                         |
+    | GitHub App Installation ID | Found in the URL your organization's app install page (Organization settings -> Github Apps -> Configure button on your app). It's the last number in the URL, ex: `https://github.com/organizations/{my-org}/settings/installations/1234567890`. |
+
+6. Depends on the usage you need to:
+
+   1. **CLI:** Export them as environment variable:
+      - `GITHUB_APP_INSTALLATION_ID`
+      - `GITHUB_APP_ID`
+      - `GITHUB_APP_PRIVATE_KEY`
+
+   2. [**GitHub Action:**](gh-action.md) Define them as GitHub secrets and use under the `with` property:
+
+      ```yaml
+      - name: GitHub CODEOWNERS Validator
+        uses: mszostok/[email protected]
+        with:
+          # ...
+          github_app_id: ${{ secrets.APP_ID }}
+          github_app_installation_id: ${{ secrets.APP_INSTALLATION_ID }}
+          github_app_private_key: ${{ secrets.APP_PRIVATE_KEY }}
+      ```
diff --git a/docs/gh-token.md b/docs/gh-token.md
diff --git a/hack/run-lint.sh b/hack/run-lint.sh
@@ -7,7 +7,7 @@ set -E         # needs to be set if we want the ERR trap
 
 CURRENT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 ROOT_PATH=$(cd "${CURRENT_DIR}/.." && pwd)
-GOLANGCI_LINT_VERSION="v1.45.2"
+GOLANGCI_LINT_VERSION="v1.46.2"
 TMP_DIR=$(mktemp -d)
 
 readonly CURRENT_DIR
@@ -26,7 +26,7 @@ host::install::golangci() {
 	export PATH="${TMP_DIR}/bin:${PATH}"
 
 	shout "Install the golangci-lint ${GOLANGCI_LINT_VERSION} locally to a tempdir..."
-	curl -sfSL -o "${TMP_DIR}/golangci-lint.sh" https://install.goreleaser.com/github.com/golangci/golangci-lint.sh
+  curl -sSfL -o "${TMP_DIR}/golangci-lint.sh" https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh
 	chmod 700 "${TMP_DIR}/golangci-lint.sh"
 
 	"${TMP_DIR}/golangci-lint.sh" -b "${TMP_DIR}/bin" ${GOLANGCI_LINT_VERSION}