Add docs for the GitHub App + Platform setup (#28)

Start the documentation

Author: System Administrator

DevExcelerateApp.sln

@@ -8,6 +8,10 @@ EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DevExcelerateApp.Tests", "tests\DevExcelerateApp.Tests\DevExcelerateApp.Tests.csproj", "{6462C529-BA10-4072-B6C6-BDDE5CE8091A}"
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "docs", "docs", "{02EA681E-C7D8-13C7-8484-4AC65E1B71E8}"
+	ProjectSection(SolutionItems) = preProject
+		docs\main.md = docs\main.md
+		docs\github-app-setup.md = docs\github-app-setup.md
+	EndProjectSection
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DevExcelerateApi", "src\DevExcelerateApi\DevExcelerateApi.csproj", "{23550023-FD87-45C8-91F7-7F3729214139}"
 EndProject

docs/github-app-setup.md

@@ -0,0 +1,92 @@
+# GitHub App Setup
+
+The following steps will guide you through the process of setting up a GitHub App for the project. This setup is essential for the bot to function correctly and interact with GitHub's WebHook events.
+
+## Step 1: Create a GitHub App
+Navigate to your organization, under settings click on "Developer settings" and then "GitHub Apps". Click on "New GitHub App". You can also navigate to the following url, replacing the organization with your own:
+`https://github.com/organizations/<organization>/settings/apps`
+
+### Step 1.1: Fill in the App Details
+- **GitHub App name**: Enter a name for your app. This will be displayed to users when they install the app.
+- **Homepage URL**: Enter the URL of your app's homepage. This can be a link to your project's GitHub repository or documentation.
+- **Webhook URL**: Enter the URL where your app will receive WebHook events. This should be the endpoint that handles incoming events from GitHub.
+- **Webhook secret**: Generate a secret key for your app. This will be used to verify the authenticity of incoming WebHook events.
+- **Permissions**: Set the permissions your app needs. For this project, you will need to set the following permissions:
+  - **Repository permissions**: 
+	- **Administration**: Read and write access
+	- **Contents**: Read and write access
+	- **Custom properties**: Read and write access
+	- **Issues**: Read and write access
+	- **Metadata**: Read-only access
+	- **Pull requests**: Read and write access
+  - **Organization permissions**: 
+	- **Custom properties**: Read-only access
+	- **Members**: Read-only access
+- **Subscribe to events**: Select the events your app will subscribe to. For this project, you will need to subscribe to the following events:
+  - **Meta**
+  - **Branch protection configuration**
+  - **Branch protection rule**
+  - **Exemption request push ruleset**
+  - **Issue comment**
+  - **Issues**
+  - **Label**
+  - **Member**
+  - **Pull Request**
+  - **Push**
+  - **Repository**
+  - **Repository ruleset**
+  - **Security and analysis**
+- **Where can this GitHub App be installed?**: only on this account
+
+### Step 1.2: Generate a Private Key
+Once your app has been created, you need to create a private key for communication. Navigate to your app, which is listed in the apps section of your organization: `https://github.com/organizations/<organization>/settings/apps`.<br/><br/>
+Click on your app, then scroll down to the "Private keys" section. Click on "Generate a private key". This will download a `.pem` file to your computer. This file is used to authenticate your app to the GitHub Platform. Upload it to your Azure Key Vault of choice.
+
+### Step 1.3 (optional): Display information
+In the General settings of the GitHub App, scroll down to the Display information section. Here, you can upload an icon and a logo for your app. These images will be displayed to users when they install the app.
+
+### Step 1.4 (optional): Configure the App managers
+In the App managers section of the GitHub App, you can add users who will be able to manage the app. This includes users who can install the app, view the app's settings, and manage the app's permissions. You can add users by their GitHub username or full name. This is optional, but it is recommended to add at least one user who will be responsible for managing the app.
+
+### Step 1.5: Install the App
+In the organization settings, under the developer settings, click on GitHub Apps. Next to the GitHub App that you want to install, click Edit. Click Install App. Click Install next to the location where you want to install the GitHub App.
+
+### Step 1.6: Configure the repository access
+In the organization settings, under Third party-access, in the GitHub Apps section, Click on the "configure" button next to your app. In the repository access section, select **All repositories**.
+
+## Step 2: Customize the organizations labels, rulesets and properties
+
+### Step 2.1: Create the labels
+In the repository that will be used for onboarding (the ones that has the issue templates), navigate to the "Issues" tab. Click on "Labels". Delete all the labels. Click on "New label". Create the following labels:
+- **APPROVED**: Support ticket approved and will be processed (Color: #7EF299)
+- **COMPLETED**: Support ticket completed (Color: #0E8A16)
+- **FAILED**: Validation checks failed (Color: #B60205)
+- **OPENE**D: Support ticket opened (Color: #1D76DB)
+- **REJECTED**: Support ticket rejected and will be closed automatically (Color: #E99695)
+- **VALIDATED**: Validation checks passed and configuration as code will be created (Color: #006B75)
+
+You can also get to this page by navigating to the following page: `https://github.com/<organization>/<onboarding-repository-name>/labels`
+
+### Step 2.2: Create the custom properties
+In the organization settings, under Repository, click on "Custom properties". Click on **New property** for each property listed below. Replace the placeholder with your appropriate values.
+**Ruleset property**<br/>
+- **Name**: <Name>-Ruleset
+- **Description**: The rulesets applied to repository using the <GitHub App name> App.
+- **Type**: Multi select
+	- Options: add as many as you see fit, depending on how many rulesets you plan to have.
+		- **<GitHub App name>-Ruleset-Default**: The default ruleset that can be applied to all repositories
+- Check the box for **Allow repository actors to set this property**.
+- Check the box for **Require this property for all repositories** and pick the default value to the default value that you have set in the options above.
+
+**<Name> property**<br/>
+This property is used as a flag to indicate that the repository was onboarded using the GitHub App.<br/>
+- **Name**: <Name>
+- **Description**: Flag to indicate that the repository was onboarded using the <GitHub App name> App
+- **Type**: true/false
+- Check the box for **Allow repository actors to set this property**.
+- Check the box for **Require this property for all repositories** and pick the default value to the default value that you have set 
+
+### Step 2.3: Create the rulesets
+In the organization settings, under Repository, click on "Rulesets". Click on "New ruleset". Select the ruleset type ou want to create whether they are branch ruleset, tag ruleset or push ruleset.<br/><br/>
+We strongly recommend to create a ruleset with the following configuration:<br/><br/>
+In Targets, under the Target repositories, pick the target **Dynamic list by property**. For the property, select the property create in Step 2.2. For the value, select the value **GitHub App**. This will ensure that the ruleset is applied to all repositories that have the property GitHub App set to GitHub App.