provide docs for GitHub auth (#126)

Author: endorama

docs/github-authentication.md

@@ -0,0 +1,19 @@
+# GitHub authentication
+
+Some commands require access to the GitHub APIs.
+
+The tool uses the GitHub token to authorize user's call to API.  
+The token can be stored in the `~/.elastic/github.token` file or passed via the `GITHUB_TOKEN` environment variable.
+
+Here are the instructions on how to create your own personal access token (PAT): [GitHub docs - Creating a personal access token][1].
+
+Make sure you have enabled the following scopes:
+* `public_repo` — to open pull requests on GitHub repositories.
+* `read:user` and `user:email` — to read your user profile information from GitHub.
+
+**NOTE**: Elastic GitHub organization uses SAML authentication, due to this PAT cannot be used for Elastic related repositories **unless authorized**.
+After creating or modifying your personal access token, authorize the token for use of the Elastic organization: [GitHub docs - Authorizing a personal access token for use with SAML single sign-on][2].
+
+[1]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
+[2]: https://docs.github.com/en/github/authenticating-to-github/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on
+

docs/usage.md

@@ -33,6 +33,8 @@ The fragment is created from the template available in [`../internal/changelog/f
 
 ### Previewing the changelog
 
+These steps require [GitHub Authentication](./github-authentication.md).
+
 From the repository root folder build the consolidated changelog with:
 
 ```
@@ -61,13 +63,17 @@ You may also be interested in  viewing the changelog for unreleased changes.
 
 ### Ensuring Changelog Fragment presence in PRs
 
+These steps require [GitHub Authentication](./github-authentication.md).
+
 `elastic-agent-chagelog-tool` has a dedicated command for this: `pr-has-fragment`.
 Given a PR number this command checks for presence of an added Changelog Fragment.
 
 For futrher details look at command usage: `elastic-agent-changelog-tool pr-has-fragment --help`
 
 ### Previewing the changelog
 
+These steps require [GitHub Authentication](./github-authentication.md).
+
 From the repository root folder build the consolidated changelog with:
 
 ```
@@ -84,6 +90,8 @@ An example is [`../changelog/0.1.0.yaml`](../changelog/0.1.0.yaml).
 
 ### Including the changelog in a pre-release version
 
+These steps require [GitHub Authentication](./github-authentication.md).
+
 Pre-release versions are development releases, it's worth including the changelog but as they are not stable releases, you should not remove the fragments.
 The side effect is that the changelog will include all entries from latest stable release up to current pre-release, but in the end this correctly reflects the content of the provided pre-release.
 
@@ -101,6 +109,8 @@ The side effect is that the changelog will include all entries from latest stabl
 
 ### Preparing the changelog
 
+These steps require [GitHub Authentication](./github-authentication.md).
+
 * Wait for the last BC of the release. If another BC is generated after that or a patch version for a previous minor is released, you might need to restart the process.
 * Create a branch **from the commit of the BC**.
 * From the root folder of the repository run: