From 6d721be5ebcad0aefb7d4308a91e01bb9de90abb Mon Sep 17 00:00:00 2001
From: james_lin <james.lin@canonical.com>
Date: Thu, 30 May 2024 16:46:00 +0800
Subject: [PATCH] Doc/terraform readme (#18)

Follow: #14
---
 terraform-plans/README.md | 65 ++++++++++++---------------------------
 1 file changed, 19 insertions(+), 46 deletions(-)

diff --git a/terraform-plans/README.md b/terraform-plans/README.md
index 248d9a0..441b263 100644
--- a/terraform-plans/README.md
+++ b/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)