update GitHub IdP doc (#2503)

* update GitHub IdP doc

* Update docs/docs/identity-providers/github.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

docs/docs/identity-providers/github.md

@@ -9,65 +9,83 @@ meta:
 
 # GitHub
 
-This document describes the use of GitHub as an identity provider for Pomerium.
+This document describes the use of GitHub as an identity provider for Pomerium. It assumes you have already [installed Pomerium](/docs/install/readme.md)
 
-Before we proceed, please be aware that [GitHub API] does not support [OpenID Connect], just [OAuth 2.0].
+::: warning
+The [GitHub API] does not support [OpenID Connect], just [OAuth 2.0].
 For this reason, it was challenging to implement revocation of a user's **Access Token** (a string representing the granted permissions) when they sign out from Pomerium's user info endpoint.
+:::
 
 In addition, the teams of the organization(s) a user belongs to, will be used as groups on Pomerium.
 
-## Setting up GitHub OAuth 2.0 for your Application
+## Create a GitHub OAuth 2.0 Application
 
 1. Log in to [Github](https://github.com/login) or create an account.
 
-2. Navigate to your profile using the avatar on the navigation bar.
+1. Navigate to your profile using the avatar on the navigation bar, and select **Settings**:
 
-3. Go to your settings.
+1. Navigate to **Developer settings ➞ OAuth Apps** and select **New OAuth App**.
 
-![GitHub settings](./img/github/github-user-profile.png)
+  ![GitHub OAuth2 Application creation](./img/github/github-oauth-creation.png)
 
-4. Click the Developers settings and create a new OAuth Application.
+1. Create a new OAuth2 application by filling the form fields above with the following parameters:
 
-![GitHub OAuth2 Application creation](./img/github/github-oauth-creation.png)
+   | Field                       | Description                                                         |
-
+   | --------------------------- | ------------------------------------------------------------------- |
-5. Create a new OAuth2 application by filling the form fields above with the following parameters:
+   | Application name            | The name of your web app.                                           |
-
+   | Homepage URL                | The homepage URL of the application to be integrated with Pomerium. |
-Field                       | Description
+   | Authorization callback URL  | `https://${authenticate_service_url}/oauth2/callback`, `authenticate_service_url` from your Pomerium configuration. |
---------------------------- | --------------------------------------------
-Application name            | The name of your web app
-Homepage URL                | The homepage URL of the application to be integrated with Pomerium
-Authorization callback URL  | `https://${authenticate_service_url}/oauth2/callback`, authenticate_service_url from pomerium configuration
 
 
-After the application had been created, you will have access to the credentials, the **Client ID** and **Client Secret**.
+1. After creating the application, select **Generate a new client secret** and save **Client Secret** along with the **Client ID**.
 
-## Service Account
+## Create a Service Account
-To use `allowed_groups` in a policy an `idp_service_account` needs to be set in the Pomerium configuration. The Service Account for GitHub should be a personal access token with `read:org` permissions, which can be created at [github.com/settings/tokens/new](https://github.com/settings/tokens/new).
 
-![Personal Access Token](./img/github/github-personal-access-token.png)
+To use `allowed_groups` in a policy, an `idp_service_account` needs to be set in the Pomerium configuration. The Service Account for GitHub should be a personal access token with `read:org` permissions
 
-The format of the `idp_service_account` for GitHub is a base64-encoded JSON document:
+1. Create a new token at [github.com/settings/tokens/new](https://github.com/settings/tokens/new).
 
-```json
+   ![Personal Access Token](./img/github/github-personal-access-token.png)
-{
+
-  "username": "YOUR_GITHUB_USERNAME",
+1. The format of the `idp_service_account` for GitHub is a base64-encoded JSON document:
-  "personal_access_token": "GENERATED_GITHUB_ACCESS_TOKEN"
+
-}
+   ```json
-```
+   {
+   "username": "YOUR_GITHUB_USERNAME",
+   "personal_access_token": "GENERATED_GITHUB_ACCESS_TOKEN"
+   }
+   ```
+
+   You can save the object as a temporary file to encode:
+
+   ```bash
+   cat tmp.json | base64 -w 0
+   ```
 
 ## Pomerium Configuration
 
-After creating your GitHub OAuth application, you can create your **Pomerium** configuration like the example below:
+After creating your GitHub OAuth application, update the **Pomerium** configuration:
 
+:::: tabs
+::: tab config.yaml
 ```bash
-authenticate_service_url: https://authenticate.localhost.pomerium.io
 idp_provider: "github"
-idp_client_id: "REDACTED"   // github application ID
+idp_client_id: "REDACTED"       // github application ID
 idp_client_secret: "REDACTED"   // github application secret
 idp_service_account: "REDACTED" // github service account (personal access token)
 ```
+:::
+::: tab Environment Variables
+```bash
+IDP_PROVIDER="github"
+IDP_CLIENT_ID="REDACTED"       // github application ID
+IDP_CLIENT_SECRET="REDACTED"   // github application secret
+IDP_SERVICE_ACCOUNT="REDACTED" // github service account (personal access token)
+```
+:::
+::::
 
-Whenever a user tries to access  your application integrated with Pomerium, they will be presented with a sign-on page as below:
+Whenever a user tries to access your application integrated with Pomerium, they will be presented with a sign-on page as below:
 
 ![GitHub Sign-on Page](./img/github/github-signon-page.png)