docs: update and consolidate documentation (#643)

* docs: update and consolidate documentation

* docs(readme): fix formatting

Author: ElioDiNino

README.md

@@ -13,15 +13,16 @@
 # The list of events the GitHub App subscribes to.
 # Uncomment the event names below to enable them.
 default_events:
-  - custom_property_values
-  - repository_ruleset
+  - branch_protection_rule
   - check_run
   - check_suite
-  - branch_protection_rule
+  - create
+  - custom_property_values
   - member
   - pull_request
   - push
   - repository
+  - repository_ruleset
   - team
 
 

app.yml

@@ -1,5 +1,21 @@
 # Deployment
 
+## Deployment Environment Variables
+
+To deploy the app anywhere, you will need 3 key environment variables:
+
+- `APP_ID`: the ID of the app, which you can get from the [app settings page](https://github.com/settings/apps).
+
+- `WEBHOOK_SECRET`: the **Webhook Secret** that you generated when you created the app.
+
+  And one of:
+
+- `PRIVATE_KEY`: (preferred approach) the contents of the private key you downloaded after creating the app, and base64 encode it ...or
+- `PRIVATE_KEY_PATH`: the path to a private key file. This will require modification for different environments to make sure the file is available. E.g. For Docker: modify the Dockerfile to COPY the file into the container.
+
+> [!NOTE]
+> `PRIVATE_KEY` takes precedence over `PRIVATE_KEY_PATH`.
+
 ## Deploy the app
 
 ### Prepare the source code
@@ -9,13 +25,13 @@ Note: If running locally without Docker, ensure that Node 16.x or later is insta
 
 - Clone the codebase
   - `git clone https://github.com/github/safe-settings.git` or `git clone <this repo>`
-  
+
 - Change directory to inside the code base
   - `cd safe-settings/`
-  
+
 - Run `npm install` to build the code
 
-- The easiest way to create the Github App is using the [manifest flow](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest#using-probot-to-implement-the-github-app-manifest-flow) . To set up the app in an org, provide the `GH_ORG` env variable in the .env file
+- The easiest way to create the Github App is using the [manifest flow](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest#using-probot-to-implement-the-github-app-manifest-flow). To set up the app in an org, provide the `GH_ORG` env variable in the .env file
 
 - If using the `manifest` flow, create `.env` from `.env.example` and set the `GH_ORG` variable if installing the app in an org.
 
@@ -26,32 +42,15 @@ Note: If running locally without Docker, ensure that Node 16.x or later is insta
 - If not using the `manifest flow` then follow the steps in [Create the GitHub App](#create-the-github-app)
 
 - Create `.env` from `.env.example`
-  
-  - `cp .env.example .env`
-  
-- Update the `.env` with the needed fields.
-
-  To deploy an app to any cloud provider, you will need 3 environment variables:
-
-- `APP_ID`: the ID of the app, which you can get from the [app settings page](https://github.com/settings/apps).
 
-- `WEBHOOK_SECRET`: the **Webhook Secret** that you generated when you created the app.
-
-And one of:
-(You will need to copy the contents of the `.pem` created from **GitHub** . This will be used when the app is built and deployed.)
-- `PRIVATE_KEY`: (preferred approach) the contents of the private key you downloaded after creating the app, and base64 encode it ...or
-- `PRIVATE_KEY_PATH`: the path to a private key file. (Modify the Dockerfile to COPY the file if this is done)
+  - `cp .env.example .env`
 
-`PRIVATE_KEY` takes precedence over `PRIVATE_KEY_PATH`.
+- Update the `.env` with the fields outlined in the [Deployment Environment Variables](#deployment-environment-variables) section
 
-Other Optional values in the .env are:    
-- `LOG_LEVEL`: Control the logging level
-- `ADMIN_REPO`: default is `admin`
-- `SETTINGS_FILE_PATH`: default is `settings.yml`
-- `DEPLOYMENT_CONFIG_FILE`: default is `deployment-settings.yml`
+Optional values in the .env file can be found under the [Environment variables](../README.md#environment-variables) section. Additionally, you can set:
 - `NODE_TLS_REJECT_UNAUTHORIZED`: `0` for ignoring SSL validation and errors
 - `GHE_HOST`: This is a required field for **GitHub Enterprise Server** implementations (_Example: github.mycompany.com_)
-- `WEBHOOK_PROXY_URL`:  SMEE Url for testing locally
+- `WEBHOOK_PROXY_URL`: SMEE Url for testing locally
 
 Once you have the `.env` file configured, you are ready to start the building of the container.
 
@@ -95,9 +94,9 @@ This will start the container in the background and detached.
 
 ### __Deploying using kubectl__
 - Create and push your image to a container registry
-- Create a `imagePullSecret` 
-  - For e.g. 
-	   `kubectl create secret docker-registry regcred --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL`   
+- Create a `imagePullSecret`
+  - For e.g.
+	   `kubectl create secret docker-registry regcred --docker-server=DOCKER_REGISTRY_SERVER --docker-username=DOCKER_USER --docker-password=DOCKER_PASSWORD --docker-email=DOCKER_EMAIL`
 - Create app secrets from the `.env` file
     `kubectl create secret generic app-env --from-env-file=.env`
 - Deploy the app
@@ -110,76 +109,64 @@ This will start the container in the background and detached.
 
 [Helm](https://helm.sh/) must be installed to use the charts. Please refer to Helm's [documentation](https://helm.sh/docs/) to get started.
 
-Once Helm is set up properly, add the Helm Repository as follows:
+Once Helm is set up properly, view the latest Helm chart version:
 
 ```bash
-$ helm repo add decyjphr https://decyjphr-org.github.io/charts/
+helm show chart oci://ghcr.io/github/helm-charts/safe-settings
 ```
 
-Once a Helm Repository is added, it can be updated as follows:
+__Configure required values__
 
+See the values that can be configured.
 ```bash
-$ helm repo update decyjphr
+helm show values oci://ghcr.io/github/helm-charts/safe-settings
 ```
 
-See the charts.
-```bash
-helm search repo safe-settings
-``` 
+Make sure to set the [Deployment Environment Variables](#deployment-environment-variables) in a `myvalues.yaml` file.
 
-__Configure required values.__  
+Optionally, you can set other values like LOG_LEVEL. See [Environment variables](../README.md#environment-variables) for more details.
 
-See the values that can be configured.
-```bash
-helm show values decyjphr/safe-settings
-``` 
+You can also override the `deploymentConfig` value.
 
-- APP_ID
-- PRIVATE_KEY
-- WEBHOOK_SECRET
+__Install the chart__
 
-Optionally, you can set other values like LOG_LEVEL.
-
-You can also override the `deploymentConfig` value.  
-
-__Install the chart__  
-Set the values for APP_ID, PRIVATE_KEY, WEBHOOK_SECRET using `--values` (Preferred approach)
+Set the values using `--values` (preferred approach)
 ```bash
-helm install safe-settings decyjphr/safe-settings --values myvalues.yaml
+helm install safe-settings oci://ghcr.io/github/helm-charts/safe-settings --values myvalues.yaml
 ```
 
-Set the with values for APP_ID, PRIVATE_KEY, WEBHOOK_SECRET using `--set`
+Set the with values using `--set`
 
 ```bash
-helm install safe-settings decyjphr/safe-settings --set appEnv.APP_ID="\"0000\"" --set appEnv.PRIVATE_KEY="TFM...==" --set appEnv.WEBHOOK_SECRET="ZjZlYTFjN...=="
+helm install safe-settings oci://ghcr.io/github/helm-charts/safe-settings --set appEnv.APP_ID="\"0000\"" --set appEnv.PRIVATE_KEY="TFM...==" --set appEnv.WEBHOOK_SECRET="ZjZlYTFjN...=="
 ```
 
-`NOTE:`Setting up Ingress controller is out of scope of this doc, but is recommended.
+> [!NOTE]
+> Setting up Ingress controller is out of scope of this doc, but is recommended.
 
 
 __If not doing an install using Helm. Generate Kubernetes YAMLs__
 ```bash
-helm template safe-settings decyjphr/safe-settings --values myvalues.yaml
+helm template safe-settings oci://ghcr.io/github/helm-charts/safe-settings --values myvalues.yaml
 ```
 
-Chart documentation is available in [decyjphr charts repo](https://github.com/decyjphr-org/charts/).
-
 *See [helm repo](https://helm.sh/docs/helm/helm_repo/) for command documentation.*
 
 **Consider using a custom image**
 
-For production use cases one should consider to build a custom safe-settings app image which conforms to your org standards. 
+For production use cases one should consider to build a custom safe-settings app image which conforms to your org standards.
 
 Follow the instructions [here](#build-the-docker-container) on how to do it.
 
 
-`NOTE:` If you want a reproducible build then you should specify a non floating tag for the image `yadhav/safe-settings:2.0.3` .
+> [!NOTE]
+> If you want a reproducible build then you should specify a non floating tag for the image `ghcr.io/github/safe-settings:2.1.10` .
 
 Once you built the image and pushed it to your registry you can specify it in your `values` file like this:
 
 ```yaml
 image:
-  repository: yadhav/safe-settings
+  repository: custom-registry/safe-settings
   pullPolicy: IfNotPresent
   # Overrides the image tag whose default is the chart appVersion.
   tag: ""
@@ -254,7 +241,7 @@ Probot runs like [any other Node app](https://devcenter.heroku.com/articles/depl
 
 Every deployment will need an [App](https://developer.github.com/apps/).
 
-1. The easiest way to create the Github App is using the [manifest flow](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest#using-probot-to-implement-the-github-app-manifest-flow) . If you set up the app using the `manifest flow`, congrats, you are DONE!
+1. The easiest way to create the Github App is using the [manifest flow](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app-from-a-manifest#using-probot-to-implement-the-github-app-manifest-flow). If you set up the app using the `manifest flow`, congrats, you are DONE!
 2. [Create a new GitHub App](https://github.com/settings/apps/new) with:
    - **Homepage URL**: the URL to the GitHub repository for your app
    - **Webhook URL**: Use `https://example.com/` for now, we'll come back in a minute to update this with the URL of your deployed app.
@@ -272,28 +259,34 @@ Every deployment will need an [App](https://developer.github.com/apps/).
 - Checks: **Read & Write**
 - Commit statuses: **Read & Write**
 - Contents: **Read & Write**
+- Custom properties: **Read & Write**
 - Issues: **Read & Write**
+- Metadata: **Read-only**
 - Pull requests: **Read & Write**
 
 #### Organization Permissions
 
-- Members: **Read & Write**
 - Administration: **Read & Write**
+- Custom properties: **Admin**
+- Members: **Read & Write**
 
 ### Events
 
 - Branch protection rule
 - Check run
 - Check suite
+- Create
+- Custom property values
 - Member
-- Push
 - Pull request
+- Push
 - Repository
+- Repository ruleset
 - Team
 
 1. Download the private key from the app.
 
-1. Make sure that you click the green **Install** button on the top left of the app page. This gives you an option of installing the app on all or a subset of your repositories. __**Important: Install this App for `All` repos in the Org**__
+2. Make sure that you click the green **Install** button on the top left of the app page. This gives you an option of installing the app on all or a subset of your repositories. __**Important: Install this App for `All` repos in the Org**__