From 84e9aa1152554933c95b14474055c5157c1536d6 Mon Sep 17 00:00:00 2001
From: justusbunsi <61625851+justusbunsi@users.noreply.github.com>
Date: Sun, 6 Jun 2021 16:35:37 +0200
Subject: [PATCH] Define configuration structure

Signed-off-by: Steven Kriegler <61625851+justusbunsi@users.noreply.github.com>
---
 .gitignore                 |  1 +
 README.md                  | 45 +++++++++++++-------------------
 config/config.example.yaml | 53 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 72 insertions(+), 27 deletions(-)
 create mode 100644 config/config.example.yaml

diff --git a/.gitignore b/.gitignore
index 6eac500..deac53c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,4 @@
 .idea/
 node_modules/
 vendor/
+config/
diff --git a/README.md b/README.md
index 5a591be..b33b93f 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,14 @@ this [won't be added in near future](https://github.com/SonarSource/sonarqube/pu
 _Gitea SonarQube PR Bot_ aims to fill the gap between working on pull requests and being notified on quality changes. 
 Luckily, both endpoints have a proper REST API to communicate with each others.
 
+## Table of Contents
+
+- [Gitea SonarQube PR Bot](#gitea-sonarqube-pr-bot)
+  - [Workflow](#workflow)
+  - [Setup](#setup)
+  - [Bot configuration](#bot-configuration)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 ## Workflow
 
@@ -26,38 +34,21 @@ Luckily, both endpoints have a proper REST API to communicate with each others.
       -> updates comment (/repos/{owner}/{repo}/issues/comments/{id})  
       -> updates status check (either failing/success)
 
-## Authentication
+## Setup
 
-- Gitea
-    - User with token to access the REST API
-    - User needs "Read project" permissions with (??at least??) access to "Pull Requests"
-- SonarQube
-    - User with token to access the REST API
-    - User needs "Browse on project" permissions
+**SonarQube**  
+- Create a user and grant permissions to "Browse on project" for the desired project
+- Create a token for this user that will be used by the bot.
+- Create a webhook pointing to `https://<bot-url>/sonarqube`. Consider securing it with a secret.
 
+**Gitea**  
+- Create a user and grant permissions to "Read project" for the desired projects including access to "Pull Requests"
+- Create a token for this user that will be used by the bot.
+- Create a project/organization/system webhook pointing to `https://<bot-url>/gitea`. Consider securing it with a secret.
 
 ## Bot configuration
 
-- SonarQube
-    - Base URL
-    - Token
-    - Webhook Secret
-- Gitea
-    - Base URL
-    - Token
-    - Webhook Secret
-
-
-## SonarQube configuration
-
-- Add user with necessary permissions
-- Create webhook pointing to the bot url (secure it with webhook secret)
-
-
-## Gitea configuration
-
-- Add user with necessary permissions
-- Create webhook on a project/organization pointing to the bot url (secure it with webhook secret)
+See [config.example.yaml](config/config.example.yaml) for a full configuration specification and description.
 
 ## Contributing
 
diff --git a/config/config.example.yaml b/config/config.example.yaml
new file mode 100644
index 0000000..fe6ed36
--- /dev/null
+++ b/config/config.example.yaml
@@ -0,0 +1,53 @@
+# Gitea related configuration. Necessary for adding/updating comments on repository pull requests
+gitea:
+  # API endpoint of your Gitea instance. Must be the API base path as shown in Swagger UI.
+  url: https://try.gitea.io/api/v1
+
+  # Created access token for the user that shall be used as bot account.
+  # User needs "Read project" permissions with access to "Pull Requests"
+  token: <...>
+
+  # If the sent webhook has a signature header, the bot validates the request payload. If the value does not match, the
+  # request will be ignored.
+  # The bot looks for `X-Gitea-Signature` header containing the sha256 hmac hash of the plain text secret. If the header
+  # exists and no webhookSecret is defined here, the bot will ignore the request, because it cannot be validated.
+  webhookSecret: {}
+  #  # either plain text
+  #  value: <...>
+  #  # or path to file containing the plain text secret
+  #  file: /path/to/gitea/webhook/secret
+
+  # List of repository the used Gitea account has access to and shall be handled by the bot. Other repository webhooks
+  # will be ignored.
+  # A repository specification contains the owner name and the repository name itself. The owner can be the name of a
+  # real account or an organization in which the repository is located.
+  repositories:
+    - owner: justusbunsi
+      name: example-repo
+    - owner: my-organization
+      name: example-repo
+
+
+# SonarQube related configuration. Necessary for requesting data from the API and processing the webhook.
+sonarqube:
+  # API endpoint of your SonarQube instance.
+  url: https://sonarcloud.io/api
+
+  # Created access token for the user that shall be used as bot account.
+  # User needs "Browse on project" permissions
+  token: <...>
+
+  # If the sent webhook has a signature header, the bot validates the request payload. If the value does not match, the
+  # request will be ignored.
+  # The bot looks for `X-Sonar-Webhook-HMAC-SHA256` header containing the sha256 hmac hash of the plain text secret.
+  # If the header exists and no webhookSecret is defined here, the bot will ignore the request, because it cannot be
+  # validated.
+  webhookSecret: {}
+  #  # either plain text
+  #  value: <...>
+  #  # or path to file containing the plain text secret
+  #  file: /path/to/gitea/webhook/secret
+
+  projects:
+    - project-1
+    - project-2