From 4f3d1aec937df8c383086f37c3ffa4575697d73c Mon Sep 17 00:00:00 2001
From: ZhengYuan Loo <me@zhengyuan.sg>
Date: Sun, 23 May 2021 16:13:43 +0800
Subject: [PATCH] docs: improve docs for github app auth

---
 website/docs/index.html.markdown | 76 ++++++++++++++++++++++++--------
 1 file changed, 58 insertions(+), 18 deletions(-)

diff --git a/website/docs/index.html.markdown b/website/docs/index.html.markdown
index 895d5793f4..f6d42dac5f 100644
--- a/website/docs/index.html.markdown
+++ b/website/docs/index.html.markdown
@@ -16,13 +16,33 @@ Use the navigation to the left to read about the available resources.
 
 ## Example Usage
 
-### OAuth / Personal Access Token Authentication
+Terraform 0.13 and later:
+
+```terraform
+terraform {
+  required_providers {
+    github = {
+      source  = "integrations/github"
+      version = "~> 4.0"
+    }
+  }
+}
 
-```hcl
+# Configure the GitHub Provider
+provider "github" {}
+
+# Add a user to the organization
+resource "github_membership" "membership_for_user_x" {
+  # ...
+}
+```
+
+Terraform 0.12 and earlier:
+
+```terraform
 # Configure the GitHub Provider
 provider "github" {
-  token = "${var.github_token}"
-  owner = "${var.github_owner}"
+  version = "~> 4.0"
 }
 
 # Add a user to the organization
@@ -31,24 +51,41 @@ resource "github_membership" "membership_for_user_x" {
 }
 ```
 
-### GitHub App Authentication
+## Authentication
+
+The GitHub provider offers multiple ways to authenticate with GitHub API.
+
+### OAuth / Personal Access Token
+
+To authenticate using OAuth tokens, ensure that the `token` argument or the `GITHUB_TOKEN` environment variable is set.
+
+```terraform
+provider "github" {
+  token = var.token # or `GITHUB_TOKEN`
+}
+```
+
+### GitHub App Installation
+
+To authenticate using a GitHub App installation, ensure that arguments in the `app_auth` block or the `GITHUB_APP_XXX` environment variables are set.
+
+Some API operations may not be available when using a GitHub App installation configuration. For more information, refer to the list of [supported endpoints](https://docs.github.com/en/rest/overview/endpoints-available-for-github-apps).
 
-```hcl
+```terraform
 provider "github" {
-  owner = var.owner
   app_auth {
-    // Empty block to allow the provider configurations to be specified through
-    // environment variables.
-    // See: https://github.com/hashicorp/terraform-plugin-sdk/issues/142
+    id              = var.app_id              # or `GITHUB_APP_ID`
+    installation_id = var.app_installation_id # or `GITHUB_APP_INSTALLATION_ID`
+    pem_file        = var.app_pem_file        # or `GITHUB_APP_PEM_FILE`
   }
 }
+```
 
-terraform {
-  required_providers {
-    github = {
-      source  = "integrations/github"
-    }
-  }
+~> **Note:** When using environment variables, an empty `app_auth` block is required to allow provider configurations from environment variables to be specified. See: https://github.com/hashicorp/terraform-plugin-sdk/issues/142
+
+```terraform
+provider "github" {
+  app_auth {} # When using `GITHUB_APP_XXX` environment variables
 }
 ```
 
@@ -56,8 +93,6 @@ terraform {
 
 The following arguments are supported in the `provider` block:
 
-* `app_auth` - (Optional) A GitHub App ID, installation ID and PEM file. When not provided or made available via respective environment variables (`GITHUB_APP_ID`, `GITHUB_APP_INSTALLATION_ID`, `GITHUB_APP_PEM_FILE`), the provider can only access resources available anonymously.
-
 * `token` - (Optional) A GitHub OAuth / Personal Access Token. When not provided or made available via the `GITHUB_TOKEN` environment variable, the provider can only access resources available anonymously.
 
 * `base_url` - (Optional) This is the target GitHub base API endpoint. Providing a value is a requirement when working with GitHub Enterprise. It is optional to provide this value and it can also be sourced from the `GITHUB_BASE_URL` environment variable. The value must end with a slash, for example: `https://terraformtesting-ghe.westus.cloudapp.azure.com/`
@@ -66,6 +101,11 @@ The following arguments are supported in the `provider` block:
 
 * `organization` - (Deprecated) This behaves the same as `owner`, which should be used instead. This value can also be sourced from the `GITHUB_ORGANIZATION` environment variable.
 
+* `app_auth` - (Optional) Configuration block to use GitHub App installation token. When not provided, the provider can only access resources available anonymously.
+  * `id` - (Required) This is the ID of the GitHub App. It can sourced from the `GITHUB_APP_ID` environment variable.
+  * `installation_id` - (Required) This is the ID of the GitHub App installation. It can sourced from the `GITHUB_APP_INSTALLATION_ID` environment variable.
+  * `pem_file` - (Required) This is the path to the GitHub App private key file. It can sourced from the `GITHUB_APP_PEM_FILE` environment variable.
+
 For backwards compatibility, if more than one of `owner`, `organization`,
 `GITHUB_OWNER` and `GITHUB_ORGANIZATION` are set, the first in this
 list takes priority.