patch: Add _sync_docs.yaml (#157)

[DPE-3641](https://warthogs.atlassian.net/browse/DPE-3641): Add
discourse-gatekeeper to data-platform-workflows.

## Description
Adding `sync-docs.yaml` workflow that uses discourse-gatekeeper action
to sync discourse docs to its corresponding GitHub repository.
- described by
[`deusebio/discourse-gatekeeper/readme.md`](https://github.com/deusebio/discourse-gatekeeper/blob/c8adb89ea1cbceca54d78da798658373615487ac/README.md)
- sample usage in
[`mysql-operator/.../sync_docs.yaml`](https://github.com/canonical/mysql-operator/blob/c7e57c086055aef58bb887f1b581cba27fb60af1/.github/workflows/sync_docs.yaml)

## Changes
- New file: `_sync_docs.yaml`
- New file: `sync_docs.md`
- Update: README.md

[DPE-3641]:
https://warthogs.atlassian.net/browse/DPE-3641?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

---------

Co-authored-by: Carl Csaposs <[email protected]>

Author: a-velasco

.github/workflows/_sync_docs.md

@@ -0,0 +1,77 @@
+Workflow file: [_sync_docs.yaml](_sync_docs.yaml)
+
+> [!WARNING]
+> Subject to **breaking changes on patch release**. `_sync_docs.yaml` is experimental & not part of the public interface.
+
+## Usage
+Add `.yaml` file to `.github/workflows/`
+
+```yaml
+# Copyright 2024 Canonical Ltd.
+# See LICENSE file for licensing details.
+name: Sync docs from Discourse
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: # Refer to Run schedule below
+  push:
+    branches:
+      - main
+
+jobs:
+  sync-docs:
+    name: Sync docs from Discourse
+    uses: canonical/data-platform-workflows/.github/workflows/[email protected]
+    secrets:
+      discourse_api_username: ${{ secrets.DISCOURSE_API_USERNAME }}
+      discourse_api_key: ${{ secrets.DISCOURSE_API_KEY }}
+    permissions:
+      contents: write  # Needed to push branch & tag
+      pull-requests: write  # Needed to create PR
+```
+
+## Run schedule
+### SQL
+| repository                | run time | cron          |
+|:-------------------------:|:--------:|:-------------:|
+| mysql-k8s-operator        | 12:00 AM | `00 00 * * *` |
+| mysql-operator            | 12:10 AM | `10 00 * * *` |
+| mysql-test-app            | 12:20 AM | `20 00 * * *` |
+| mysql-router-k8s-operator | 12:30 AM | `30 00 * * *` |
+| mysql-router-operator     | 12:40 AM | `40 00 * * *` |
+| postgresql-k8s-operator   | 12:50 AM | `50 00 * * *` |
+| postgresql-operator       | 01:00 AM | `00 01 * * *` |
+| postgresql-test-app       | 01:10 AM | `10 01 * * *` |
+| pgbouncer-k8s-operator    | 01:20 AM | `20 01 * * *` |
+| pgbouncer-operator        | 01:30 AM | `30 01 * * *` |
+
+### NoSQL
+| repository                     | run time | cron          |
+|:------------------------------:|:--------:|:-------------:|
+| mongodb-k8s-operator           | 01:40 AM | `40 01 * * *` |
+| mongodb-operator               | 01:50 AM | `50 01 * * *` |
+| mongos-operator                | 02:00 AM | `00 02 * * *` |
+| opensearch-k8s-operator        | 02:10 AM | `10 02 * * *` |
+| opensearch-operator            | 02:20 AM | `20 02 * * *` |
+| opensearch-dashboards-operator | 02:30 AM | `30 02 * * *` |
+| redis-k8s-operator             | 02:40 AM | `40 02 * * *` |
+| redis-operator                 | 02:50 AM | `50 02 * * *` |
+
+### Big Data
+| repository                        | run time | cron          |
+|:---------------------------------:|:--------:|:-------------:|
+| kafka-k8s-operator                | 03:00 AM | `00 03 * * *` |
+| kafka-operator                    | 03:10 AM | `10 03 * * *` |
+| kafka-test-app                    | 03:20 AM | `20 03 * * *` |
+| zookeeper-k8s-operator            | 03:30 AM | `30 03 * * *` |
+| zookeeper-operator                | 03:40 AM | `40 03 * * *` |
+| spark-history-server-k8s-operator | 03:50 AM | `50 03 * * *` |
+| spark-client-snap                 | 04:00 AM | `00 04 * * *` |
+
+### Other
+| repository         | run time | cron          |
+|:------------------:|:--------:|:-------------:|
+| data-integrator    | 04:10 AM | `10 04 * * *` |
+| s3-integrator      | 04:20 AM | `20 04 * * *` |
+| data-platform-libs | 04:30 AM | `30 04 * * *` |

.github/workflows/_sync_docs.yaml

@@ -0,0 +1,31 @@
+on:
+  workflow_call:
+    secrets:
+      discourse-api-user:
+        description: Discourse API username
+        required: true
+      discourse-api-key:
+        description: Discourse API key
+        required: true
+
+jobs:
+  sync-docs:
+    name: Sync Discourse docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Open PR with changes to Discourse topics
+        uses: deusebio/discourse-gatekeeper@c8adb89ea1cbceca54d78da798658373615487ac
+        id: docs-pr
+        with:
+          discourse_host: discourse.charmhub.io
+          discourse_api_username: ${{ secrets.discourse-api-user }}
+          discourse_api_key: ${{ secrets.discourse-api-key }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          dry_run: "true"
+      - name: Show migrate output
+        run: echo '${{ steps.docs-pr.outputs.migrate }}'
+      - name: Show reconcile output
+        run: echo '${{ steps.docs-pr.outputs.reconcile }}'

README.md

@@ -12,6 +12,7 @@
 | [release_charm.yaml](.github/workflows/release_charm.md)                   | Release charm to Charmhub                                                  |
 | [update_bundle.yaml](.github/workflows/update_bundle.md)                   | Update charm revisions in bundle                                           |
 | [sync_issue_to_jira.yaml](.github/workflows/sync_issue_to_jira.md)         | Sync GitHub issues to Jira issues                                          |
+| [_sync_docs.yaml](.github/workflows/_sync_docs.md)                         | **Experimental** Sync Discourse documentation to GitHub                    |
 
 ### Version
 Recommendation: pin the latest version (e.g. `v1.0.0`) and use [Renovate](https://docs.renovatebot.com/) to stay up-to-date.