docs: improve docs for github app auth (#801)

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,33 +51,48 @@ 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:/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:/hashicorp/terraform-plugin-sdk/issues/142
+
+```terraform
+provider "github" {
+ app_auth {} # When using `GITHUB_APP_XXX` environment variables
 }
 ```
 
 ## Argument Reference
 
 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.