From 9c11a7ec837784dd5522565f9c73357956a376ca Mon Sep 17 00:00:00 2001 From: Kalibh Halford Date: Thu, 17 Oct 2024 11:24:57 +0100 Subject: [PATCH 1/3] DOC: Update docs and add template files --- cloud-chatops/README.md | 129 +++++++++++++++++++++++----- cloud-chatops/template_config.yml | 26 ++++++ cloud-chatops/template_secrets.json | 5 ++ 3 files changed, 140 insertions(+), 20 deletions(-) create mode 100644 cloud-chatops/template_config.yml create mode 100644 cloud-chatops/template_secrets.json diff --git a/cloud-chatops/README.md b/cloud-chatops/README.md index d354ba5..09fe6fd 100644 --- a/cloud-chatops/README.md +++ b/cloud-chatops/README.md @@ -1,27 +1,116 @@ -# Cloud Slack Workspace App -## About -Using Slack's Bolt for Python library here I have developed a Slack Application currently running in the Cloud Slack Workspace.
-This application is designed to help promote the closing of GitHub pull requests either by getting them approved and merged or closed when they go stale.
-In principle, the app will notify authors about their pull requests until they are closed.
+# Cloud ChatOps +![Build](https://github.com/stfc/cloud-docker-images/actions/workflows/cloud_chatops.yaml/badge.svg) +[![codecov](https://codecov.io/gh/stfc/cloud-docker-images/graph/badge.svg?token=BZEBAE0TQD)](https://codecov.io/gh/stfc/cloud-docker-images) + +## Contents: +[About](#about)
+[Usage / Features](#usage--features)
+[Deployment](#deployment)
+[requirements](#requirements)
+ +### About + +Cloud ChatOps is designed to help promote the closing of GitHub pull requests. Either by getting them approved and merged or closed when they go stale.
+The app will notify authors about their pull requests until they are closed / merged. There are multiple methods of sending these reminders.
+ +### Usage / Features + +The main purpose of this application is to remind the team about pull requests they have open across their GitHub repositories.
+This is facilitated by the below features which can be found in [main.py](src/main.py). + +#### Slash Commands: +These slash commands can be run in any channel the application has access to.
+ - `/prs `: Sends a private message to the user with a list of open pull requests. Either user authored or by anyone. + +#### Scheduled Events: +Using the [schedule](https://pypi.org/project/schedule/) library functions are triggered on a weekly basis.
+Events are defined in the `schedule_jobs` function:
+- `run_global_reminder()`: Sends a message to the pull request channel with every open pull request across the repositories in a thread. +- `run_personal_reminder()`: Sends a message to each user directly with a thread of their open pull requests. + ### Deployment -The entry point for is in [main.py](src/main.py) which will run the application.
-The required files (below) need to be in the [cloud_chatops]() directory.
-### Functionality -As of current, the application gets all open pull requests from any Cloud owned repository and will send a message to our pull-request channel about each pull request notifying the author.
-The app runs on an asynchronous loop scheduling each reminder to be sent out on days of our catch-ups (Monday, Wednesday and Friday).
-On Mondays the application will mention users with **@** as to notify them directly. However, on the other 2 days authors will not be mentioned as to not spam people.
+ +Secrets should always be stored in `$HOME/cloud_chatops_secrets` on the host system. Find out more about secrets [here](#Secrets)
+The application can be run from a Docker image or source code. (Assuming running from project root)
+ +#### Docker image: +You can build the image locally or pull from [STFC Harbor](https://harbor.stfc.ac.uk).
+Note: If you are pulling the image you will need to specify a version tag. +The latest version can be found in [version.txt](version.txt)
+- ```shell + # Local build and run + docker build -t cloud_chatops cloud-chatops + docker run -v $HOME/cloud_chatops_secrets/:/usr/src/app/cloud_chatops_secrets/ cloud_chatops -d + ``` +- ```shell + # Pull from harbor and run + docker run -v $HOME/cloud_chatops_secrets/:/usr/src/app/cloud_chatops_secrets/ harbor.stfc.ac.uk/stfc-cloud/cloud-chatops: -d + ``` + +#### Running from source: +You can run the code from [main.py](src/main.py).
+It's always recommended to create a [virtual environment](https://docs.python.org/3/library/venv.html) +for the application to run before installing dependencies. +- ```shell + source my_venv/bin/activate + pip3 install -r requirements.txt + python3 cloud-chatops/src/main.py prod + ``` + + + + + + ### Requirements: -The following files need to be present in the working directory of the application.
-- **repos.csv**: A list of repositories owned by `stfc` (e.g. `repo1,repo2,repo3`).
-- **user_map.json**: A dictionary of GitHub usernames to Slack Member IDs (e.g. `{"khalford":"ABC123"}`).
-- **secrets.json**: A dictionary of token names to token values (e.g. `{"SLACK_APP_TOKEN":"123ABC"}`).
-- **maintainer.txt**: A text file containing the maintainer users Slack Member ID. -For `secrets.json` the following token structure can be used:
+Two files required for the deployment of this application: `config.yml` and `secrets.json`.
+These should be stored in `$HOME/cloud_chatops_secrets` on the host system.
+ +#### Config +The application configuration is stored in [config.yml](template_config.yml). +This includes information such as username mapping, repositories to check and default values.
+The `config.yml` should look like the below: +```yaml +--- +maintainer: AB12CD34 # Slack Member ID of the application maintainer + +user-map: # Dictionary of GitHub username to Slack Member ID + my_github_username: AB12CD34 + other_github_username: EF56GH78 + +repos: # Dictionary of owners and repositories + organisation1: + - repo1 # E.g. github.com/organisation1/repo1 + - repo2 + - repo3 + organisation2: + - repo1 # E.g. github.com/organisation2/repo1 + - repo2 + - repo3 + +defaults: # Default values for application variables + # Default author will be assigned to pull requests where the PR author is not in the above user map. + # Usually team lead or senior staff member. + author: WX67YZ89 # Slack member ID + + # Default channel is where the pull requests will be posted. + # It's recommended to set this as a "maintenance" / "dev" channel in case the application goes awry. + # The actual channel messages are sent to can be specified in the code. + channel: CH12NN34 # Slack channel ID +``` +#### Secrets + +The application needs secrets for Slack and GitHub.
+TODO: How to run your own Slack application or find on slack marketplace.
+A GitHub Personal Access Token is needed to bypass rate limiting and allows access to private repositories.
+Documentation on how to create a GitHub personal access token can be found +[here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+The `secrets.json` file should look like the below and there is a template [here](template_secrets.json) ```json { - "SLACK_BOT_TOKEN": "ABC123", - "SLACK_APP_TOKEN": "CDE456", - "GITHUB_TOKEN": "FGH789", + "SLACK_BOT_TOKEN": "", + "SLACK_APP_TOKEN": "", + "GITHUB_TOKEN": "" } ``` diff --git a/cloud-chatops/template_config.yml b/cloud-chatops/template_config.yml new file mode 100644 index 0000000..06d9637 --- /dev/null +++ b/cloud-chatops/template_config.yml @@ -0,0 +1,26 @@ +--- +maintainer: AB12CD34 # Slack Member ID of the application maintainer + +user-map: # Dictionary of GitHub username to Slack Member ID + my_github_username: AB12CD34 + other_github_username: EF56GH78 + +repos: # Dictionary of owners and repositories + organisation1: + - repo1 # E.g. github.com/organisation1/repo1 + - repo2 + - repo3 + organisation2: + - repo1 # E.g. github.com/organisation2/repo1 + - repo2 + - repo3 + +defaults: # Default values for application variables + # Default author will be assigned to pull requests where the PR author is not in the above user map. + # Usually team lead or senior staff member. + author: WX67YZ89 # Slack member ID + + # Default channel is where the pull requests will be posted. + # It's recommended to set this as a "maintenance" / "dev" channel in case the application goes awry. + # The actual channel messages are sent to can be specified in the code. + channel: CH12NN34 # Slack channel ID diff --git a/cloud-chatops/template_secrets.json b/cloud-chatops/template_secrets.json new file mode 100644 index 0000000..1b9282f --- /dev/null +++ b/cloud-chatops/template_secrets.json @@ -0,0 +1,5 @@ +{ + "SLACK_BOT_TOKEN": "", + "SLACK_APP_TOKEN": "", + "GITHUB_TOKEN": "" +} \ No newline at end of file From e9b4b85580eecf1eed2fc96fbb04134db5686754 Mon Sep 17 00:00:00 2001 From: Kalibh Halford Date: Thu, 17 Oct 2024 14:46:49 +0100 Subject: [PATCH 2/3] MAINT: Bump Version --- cloud-chatops/version.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloud-chatops/version.txt b/cloud-chatops/version.txt index 9084fa2..524cb55 100644 --- a/cloud-chatops/version.txt +++ b/cloud-chatops/version.txt @@ -1 +1 @@ -1.1.0 +1.1.1 From fd2f3b7d4b78adfbc762a0c706107619720ca58a Mon Sep 17 00:00:00 2001 From: Kalibh Halford Date: Fri, 18 Oct 2024 10:27:56 +0100 Subject: [PATCH 3/3] DOC: PR changes for readability --- cloud-chatops/README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/cloud-chatops/README.md b/cloud-chatops/README.md index 09fe6fd..9f48416 100644 --- a/cloud-chatops/README.md +++ b/cloud-chatops/README.md @@ -10,8 +10,9 @@ ### About -Cloud ChatOps is designed to help promote the closing of GitHub pull requests. Either by getting them approved and merged or closed when they go stale.
-The app will notify authors about their pull requests until they are closed / merged. There are multiple methods of sending these reminders.
+Cloud ChatOps is designed to help encourage developers to complete GitHub pull requests. +Either by getting them approved and merged or closed when they go stale.
+The app will notify authors about their pull requests, usually by Slack, until they are closed / merged. There are multiple methods of sending these reminders.
### Usage / Features @@ -34,7 +35,7 @@ Secrets should always be stored in `$HOME/cloud_chatops_secrets` on the host sys The application can be run from a Docker image or source code. (Assuming running from project root)
#### Docker image: -You can build the image locally or pull from [STFC Harbor](https://harbor.stfc.ac.uk).
+You can build the image locally or pull from [STFC Harbor](https://harbor.stfc.ac.uk/harbor/projects/33528/repositories/cloud-chatops).
Note: If you are pulling the image you will need to specify a version tag. The latest version can be found in [version.txt](version.txt)
- ```shell @@ -70,6 +71,11 @@ These should be stored in `$HOME/cloud_chatops_secrets` on the host system.
#### Config The application configuration is stored in [config.yml](template_config.yml). This includes information such as username mapping, repositories to check and default values.
+Slack Channel and Member IDs can be found in Slack by:
+- Right-clicking the member / channel +- View member / channel details +- Near the bottom of the About tab there will be an ID with copy button + The `config.yml` should look like the below: ```yaml ---