Doc/terraform readme (#18)

Follow: #14

terraform-plans/README.md

@@ -1,48 +1,21 @@
 # Terraform plans for Solution Engineering
 
-Currently these plans are only for setting GitHub repos and to add workflow files.
-
-## How to start
-
-1. Initialize Terraform.
-
-```bash
-terraform init
-```
-
-1. [Optional] If it's used locally for multiple repos. Create a workspace for each repo, otherwise terraform will try to overwrite the existing resource, e.g. repo.
-
-```bash
-terraform workspace new <repo-name>
-```
-
-1. Set GitHub authenetication for GitHub application.
-```bash
-export GITHUB_APP_ID="1234"
-export GITHUB_APP_INSTALLATION_ID="56789"
-export GITHUB_APP_PEM_FILE=$(cat ./my-app.private-key.pem)
-```
-
-1. [Optional] Create custom configuration or use one of defined in config directory.
-
-```tfvars
-owner      = "<owner/org name>"
-repository = "<repo name>"
-branch     = "main"
-workflow_files = {
-  jira_sync_config = {
-    source      = "./files/workflows/jira_sync_config.yaml"
-    destination = ".github/workflows/jira_sync_config.yaml"
-  }
-  codeowners = {
-    source      = "./files/workflows/CODEOWNERS"
-    destination = ".github/CODEOWNERS"
-  }
-}
-```
-
-1. Generate Terraform plan to validate it.
-
-```bash
-terraform plan -var-file=configs/github.tfvars -var-file=configs/soleng-tf-test-repo.tfvars
-```
+## Rationale
+
+Solution engineer team use terraform to make sure the github repositories have consistent repository settings and workflow files.
+The terraform init/plan/apply will run automatically on the Github action.
+
+## Permissions
+
+We use [Terraform Github Provider](https://registry.terraform.io/providers/integrations/github/latest/docs) to interact with Github resources. And this provider has multiple ways to to authenticate with Github API. We use Github application for authentication.
+
+> For more details how to use Github application authentication, please check [Terraform Github Provider - Github App Installation](https://registry.terraform.io/providers/integrations/github/latest/docs#github-app-installation)
+
+The permissions required for the github application are:
+
+-  Read access to members and metadata
+-  Read and write access to actions, actions variables, administration, checks, code, commit statuses, environments, issues, merge queues, packages, pull requests, secrets, and workflows
+
+> This Github Application need to be installed on every repositories we want to manage. Please ask people who has Github Organization permission for help.
+> 
+> For how to create the github application, please check [Creating Github Apps](https://docs.github.com/en/apps/creating-github-apps)