Add documentation about the GitHub token

README.md

@@ -1,15 +1,19 @@
+<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/>
+
+## Codeowners Validator
+
+<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>
 
----
 
 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.
 
@@ -96,7 +100,7 @@ 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_ACCESS_TOKEN</tt>| | The GitHub access token. Instruction for creating a token can be found [here](./docs/gh-token.md). 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` |

docs/README.md

@@ -0,0 +1,9 @@
+<h1>
+    <img alt="logo" src="./assets/codeowners-validator-logo-black.png" width="10px" />
+</h1>
+
+Welcome to the codeowner-validator documentation.
+
++ [**GitHub Action**](./gh-action.md) - list of supported providers and any gotchas
++ [**GitHub personal access token**](./gh-token.md)
++ [**Release**](./release.md)

docs/gh-token.md

@@ -0,0 +1,19 @@
+[← 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 because of those reasons:
+
+1. Information about organization teams and their repositories are not publicly available.
+2. If you are setting GitHub Enterprise base URL then an unauthorized error can 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 big organization where you have a lot of call between you infrastructure server and GitHub site it is easy to exceed that quota. 
+
+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). The token only need to have the readonly scopes but the scope differ between public and private repositories.
+
+#### For the public repositories you should select `public_repo` and `read:org`:
+
+![token-public.png](./assets/token-public.png) 
+
+#### For the private repositories you should select `repo` and `read:org`:
+
+![token-public.png](./assets/token-private.png) 

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.