📝 update docs (#63)

JoshuaTheMiller · web-flow · commit bca4a5fc1ee7 · 2024-01-04T13:38:02.000Z
Related to #16 * add details, fix wording, etc.
diff --git a/README.md b/README.md
@@ -19,71 +19,19 @@ Before submitting a new Feature request, please check existing open and closed I
 
 ```sh
 # Run the application in "dev" mode and watch for changes
-npm start
+npm run dev
 # Generate models from the openapi definition
 npm run openapi
 ```
 
-## Configuration File
+## Application Configuration
 
-This service/Action requires that a configuration file be present in the `.github` repository of your GitHub Organization. An example of this is show below:
+🚧 Coming soon...
 
-Filename: `team-sync-options.yaml`
-```yaml
-# This property is used to set the Owners of the Organization. Currently, this will NOT 
-# remove anyone who was manually added as an Owner to the org.
-OrganizationOwnersGroup: Some_Org_Owner_Group
+## Per-Organization Configuration
 
-# This property is used to control the addition of general Members to your Organization.
-OrganizationMembersGroup: Some_Group_To_Sync_For_Organization_Membership
+See [./docs/OrganizationConfiguration.md](./docs/OrganizationConfiguration.md) for further details!
 
-# This property is used for syncing all other GitHub Teams. Please note that users must also 
-# be a part of the `OrganizationMembersGroup` for the synchronization of the teams below to 
-# function properly.
-# Note: this is a convenience property. The `Teams` property allows for more complex
-# setup of teams (i.e., display names and eventually parent/child relationships).
-GitHubTeamNames:
-- Some_Team_To_Sync
-- Some_Other_Team_To_Sync
+## Running the sync bot
 
-# Allows Organizations to add their own Security Manager teams in addition to those set at 
-# the app level. 
-# Note: this property supports Display Names.
-AdditionalSecurityManagerGroups:
-- Name: Some_SecurityManager_Team
-- Name: Some_SecurityManager_Team_2
-  DisplayName: Some Security Manager Team 2
-
-# This property is used for syncing all other GitHub Teams. Please note that users must also 
-# be a part of the `OrganizationMembersGroup` for the synchronization of the teams below to 
-# function properly.
-# Note: this property supports Display Names.
-Teams:
-- Name: Some_Team
-- Name: Some_Team_2
-  DisplayName: Some Team 2
-```
-
-## Necessary configuration of the tool/service
-
-As of this writing, this sync tool can be ran as a standalone app, or as a GitHub Action.
-
-### As a Standalone App
-
-An Azure AD App registration must be created with the following permissions:
-
-* **Application** Permission: `GroupMember.Read.All`
-* **Application** Permission: `User.Read.All`
-
-The Client ID and Client Secret must be provided as environment variables to the application.
-
-A GitHub App registration must be created with the following permissions (this information should be moved to an `app.yml file` instead of being documented here):
-
-* Repository- Contents: Read (only necessary for the `.github` repository)
-* Repository- Deployments: Read and Write (only necessary for the `.github` repository)
-* Organization- Members: Read and Write
-* Organization- Administration: Read and Write
-    * This is needed for managing [Security Managers](https://docs.github.com/en/enterprise-cloud@latest/rest/orgs/security-managers?apiVersion=2022-11-28), though as Security Managers is in beta, this permission may also change.
-    * ❗ **If you do not intend to use this functionality**, feel free to exclude this permission from your GitHub App Registration
-
-The AppId and Private Key must be provided as environment variables to the application.
+See [./docs/RunningTheApp.md](./docs/RunningTheApp.md) for further details!
diff --git a/docs/ApplicationConfiguration.md b/docs/ApplicationConfiguration.md
@@ -0,0 +1,31 @@
+# Application Configuration
+
+Your local `.env` file will look like the following:
+
+```shell
+# AppId from the GitHub App Registration
+GitHubApp__AppId=
+# The Private Key from the GitHub App Registration
+GitHubApp__PrivateKey=
+
+# Text that is appended to the end of a username that is fetched from the 
+# source of truth.
+APP_OPTIONS_GitHubIdAppend=
+
+# The GitHub Org to look towards for additional application configuration
+APP_OPTIONS_AppConfigOrg=
+# The GitHub Repository to look towards for additional application configuration
+APP_OPTIONS_AppConfigRepo=team-sync-bot-ops
+
+# The LDAP Configuration. Eventually this will be moved to a plugin
+LDAP_SERVER=
+LDAP_USER=
+LDAP_PASSWORD=
+LDAP_GROUP_BASE_DN=
+
+# Optional
+APP_OPTIONS_RedisHost=
+GITHUB_PROXY=
+SOURCE_PROXY=
+PORT=
+```
diff --git a/docs/GitHubAppRegistration.md b/docs/GitHubAppRegistration.md
@@ -0,0 +1,32 @@
+# Configuring the GitHub App Registration
+
+As this bot interacts with Github, it needs a GitHub App registration to be created for proper authentication.
+
+## Permissions
+
+This bot currently requires a GitHub App Registration to have the following permissions:
+
+```yaml
+repository:contents: Read-only
+repository:deployments: Read-and-write # Under review for removal
+repository:metadata: Read-only
+
+organization:administration: Read-and-write # See note about Organization Administration Note below
+organization:members: Read-and-write
+
+# Upcoming
+repository:checks: Read-and-write
+repository:commit-statuses: Read-and-write
+repository:pull-requests: Read
+
+organization:github-copilot-business: Read-and-write
+```
+
+## Events
+
+TBD
+
+## Organization Administration Note
+
+* This permission is needed for managing [Security Managers](https://docs.github.com/en/enterprise-cloud@latest/rest/orgs/security-managers?apiVersion=2022-11-28), though as Security Managers is in beta, this permission may also change.
+* ❗ **If you do not intend to use this functionality**, feel free to exclude this permission from your GitHub App Registration
diff --git a/docs/OrganizationConfiguration.md b/docs/OrganizationConfiguration.md
@@ -0,0 +1,39 @@
+# Organization Configuration
+
+This service/Action requires that a configuration file be present in the `.github` repository of your GitHub Organization. An example of this is show below:
+
+Filename: `team-sync-options.yaml`
+```yaml
+# This property is used to set the Owners of the Organization. Currently, this will NOT 
+# remove anyone who was manually added as an Owner to the org.
+OrganizationOwnersGroup: Some_Org_Owner_Group
+
+# This property is used to control the addition of general Members to your Organization.
+OrganizationMembersGroup: Some_Group_To_Sync_For_Organization_Membership
+
+# This property is used for syncing all other GitHub Teams. Please note that users must also 
+# be a part of the `OrganizationMembersGroup` for the synchronization of the teams below to 
+# function properly.
+# Note: this is a convenience property. The `Teams` property allows for more complex
+# setup of teams (i.e., display names and eventually parent/child relationships).
+GitHubTeamNames:
+- Some_Team_To_Sync
+- Some_Other_Team_To_Sync
+
+# Allows Organizations to add their own Security Manager teams in addition to those set at 
+# the app level. 
+# Note: this property supports Display Names.
+AdditionalSecurityManagerGroups:
+- Name: Some_SecurityManager_Team
+- Name: Some_SecurityManager_Team_2
+  DisplayName: Some Security Manager Team 2
+
+# This property is used for syncing all other GitHub Teams. Please note that users must also 
+# be a part of the `OrganizationMembersGroup` for the synchronization of the teams below to 
+# function properly.
+# Note: this property supports Display Names.
+Teams:
+- Name: Some_Team
+- Name: Some_Team_2
+  DisplayName: Some Team 2
+```
diff --git a/docs/RunningTheApp.md b/docs/RunningTheApp.md
@@ -0,0 +1,71 @@
+# Running the Groups to Teams Sync Bot
+
+This application is written to be operating system agnostic. If it does not work properly on a particular operating system, submit an Issue detailing your setup and problem.
+
+We strive to make successfully running and building this application fairly straightforward. The steps are as follows:
+
+1. Install the necessary tooling
+2. Prepare your GitHub App registration
+3. Prepare your source-of-truth credentials
+4. Configure the app
+5. Run the app
+
+## 1 Prerequisite Tooling
+
+* NodeJS v20: https://nodejs.org/en/learn/getting-started/how-to-install-nodejs
+
+### Optional
+
+* A container runtime and builder- Docker, Podman, etc.
+    * Docker: https://docs.docker.com/get-docker/
+    * Podman: https://podman.io/docs
+
+## 2 GitHub App Registration
+
+See [./GitHubAppRegistration.md](./GitHubAppRegistration.md).
+
+## 3 Source of Truth credentials
+
+At this point in time, the logic to fetch information from an LDAP system is baked into this application. Eventually it will be moved to a plugin to make running and developing this application simpler.
+
+At this point in time, you will need to provide 4 values in the application configuration for LDAP:
+
+```sh
+LDAP_SERVER=
+LDAP_USER=
+LDAP_PASSWORD=
+LDAP_GROUP_BASE_DN=
+```
+
+## 4 Configure the App
+
+See [./ApplicationConfiguration.md](./ApplicationConfiguration.md).
+
+## 5 Run the App
+
+With all the prerequisites out of the way, the following commands will now allow you to run the app:
+
+```sh
+npm install
+npm run dev
+```
+
+After running the commands above, you should eventually see console output similar to the following:
+
+```sh
+> teams-sync@1.0.0 dev
+> nodemon
+
+[nodemon] 3.0.2
+[nodemon] to restart at any time, enter `rs`
+[nodemon] watching path(s): src\**\*
+[nodemon] watching extensions: ts,json,yaml
+[nodemon] starting `ts-node ./src/app.ts`
+{
+  HostPort: '8080',
+  ForwardingGitHubRequestsTo: 'Not forwarding',
+  ForwardingGroupRequestsTo: 'Not forwarding',
+  RedisCacheHost: 'No cache'
+}
+Connected to LDAP Server
+```
diff --git a/package.json b/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "teams-sync-rewrite",
+  "name": "teams-sync",
   "version": "1.0.0",
   "description": "",
   "main": "app.ts",

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "name": "teams-sync-rewrite",`
	`2`	`+ "name": "teams-sync",`
`3`	`3`	`"version": "1.0.0",`
`4`	`4`	`"description": "",`
`5`	`5`	`"main": "app.ts",`