Add documentation about the GitHub token

README.md

@@ -1,17 +1,21 @@
+<br/>
+<br/>
 <p align="center">
-  <h3 align="center">GitHub CODEOWNERS Validator</h3>
+  <img alt="logo" src="./docs/assets/logo.png" width="320px"/>
   <p align="center">Ensures the correctness of your CODEOWNERS file.</p>
-  <p align="center">
-    <a href="/LICENSE"><img alt="Software License" src="https://img.shields.io/badge/license-Apache-brightgreen.svg?style=flat-square"></a>
-    <a href="https://goreportcard.com/report/github.com/goreleaser/godownloader"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/mszostok/codeowners-validator?style=flat-square"></a>
-    <a href="https://travis-ci.org/goreleaser/godownloader"><img alt="Travis" src="https://img.shields.io/travis/com/mszostok/codeowners-validator/master.svg?style=flat-square"></a>
-    <!-- <a href="http://godoc.org/github.com/mszostok/codeowners-validator"><img alt="Go Doc" src="https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square"></a> --> 
-  </p>
 </p>
+<br/>
+<br/>
+<br/>
+<br/>
 
----
+## Codeowners Validator
 
-The Codeowners Validator project validates the GitHub [CODEOWNERS](https://help.github.com/articles/about-code-owners/) file using [those checks](#checks). It supports public and private GitHub repositories and also GitHub Enterprise installations.
+<a href="/LICENSE"><img alt="Software License" src="https://img.shields.io/badge/license-Apache-brightgreen.svg?style=flat-square"/></a>
+<a href="https://goreportcard.com/badge/github.com/mszostok/codeowners-validator"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/mszostok/codeowners-validator?style=flat-square"/></a>
+<a href="https://travis-ci.com/github/mszostok/codeowners-validator"><img alt="Travis" src="https://img.shields.io/travis/com/mszostok/codeowners-validator/master.svg?style=flat-square"/></a>
+
+The Codeowners Validator project validates the GitHub [CODEOWNERS](https://help.github.com/articles/about-code-owners/) file based on [specified checks](#checks). It supports public and private GitHub repositories and also GitHub Enterprise installations.
 
 ![usage](./docs/assets/usage.svg)
 
@@ -95,11 +99,11 @@ Use the following environment variables to configure the application:
 
 | Name | Default | Description |
 |-----|:--------|:------------|
-| <tt>REPOSITORY_PATH</tt> <b>*</b> | | The repository path to your repository on your local machine. |
-| <tt>GITHUB_ACCESS_TOKEN</tt>| | 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. |
-| <tt>GITHUB_BASE_URL</tt>| https://api.github.com/ | 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. |
-| <tt>GITHUB_UPLOAD_URL</tt> | https://uploads.github.com/ | The GitHub upload URL for uploading files. <br> <br>It is taken into account only when the `GITHUB_BASE_URL` is also set. If only the `GITHUB_BASE_URL` is provided then this parameter defaults to the `GITHUB_BASE_URL` value. |
-| <tt>CHECKS</tt>| - |  The list of checks that will be executed. By default, all checks are executed. Possible values: `files`,`owners`,`duppatterns` |
+| <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_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>CHECKS</tt>| - |  List of checks to be executed. By default, all checks are executed. Possible values: `files`,`owners`,`duppatterns`. |
 | <tt>EXPERIMENTAL_CHECKS</tt> | - | The comma-separated list of experimental checks that should be executed. By default, all experimental checks are turned off. Possible values: `notowned`.|
 | <tt>CHECK_FAILURE_LEVEL</tt> | `warning` | Defines the level on which the application should treat check issues as failures. Defaults to `warning`, which treats both errors and warnings as failures, and exits with error code 3. Possible values are `error` and `warning`. |
 | <tt>OWNER_CHECKER_REPOSITORY</tt>  <b>*</b>| | The owner and repository name separated by slash. For example, gh-codeowners/codeowners-samples. Used to check if GitHub owner is in the given organization. |

docs/README.md

@@ -0,0 +1,10 @@
+<h1>
+    <img alt="logo" src="./assets/logo-small.png" width="28px" />
+    Codeowners Validator documentation
+</h1>
+
+Welcome to the Codeowners Validator documentation.
+
++ [GitHub Action](./gh-action.md)
++ [GitHub personal access token](./gh-token.md)
++ [Release](./release.md)

docs/gh-action.md

@@ -1,3 +1,5 @@
+[← back to docs](./README.md)
+
 <p align="center">
   <h3 align="center">GitHub Action for CODEOWNERS Validator</h3>
   <p align="center">Ensures the correctness of your CODEOWNERS file.</p>
@@ -6,8 +8,7 @@
   </p>
 </p>
 
----
-
+##
 The [Codeowners Validator](https://github.com/mszostok/codeowners-validator) is available as a GitHub Action.
 
 <p align="center">

docs/gh-token.md

@@ -0,0 +1,25 @@
+[← back to docs](./README.md)
+
+# GitHub personal access token
+
+The [valid_owner.go](./../internal/check/valid_owner.go) check requires the GitHub personal access 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. 
+
+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) 
+
+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 more strict about the software run in its infrastructure.

docs/release.md

@@ -1,3 +1,5 @@
+[← back to docs](./README.md)
+
 # Release process
 
 The release of the codeowners-validator tool is performed by the [GoReleaser](https://github.com/goreleaser/goreleaser) which builds Go binaries for several platforms and then creates a GitHub release.