Add support for merge gate in CI workflow (#250)

---------
Co-authored-by: Christoph Kuhnke <christoph.kuhnke@exasol.com>

Author: Nicoretti

.github/workflows/ci-cd.yml .github/workflows/cd.yml.github/workflows/ci-cd.yml renamed to .github/workflows/cd.yml

@@ -1,4 +1,4 @@
-name: CI/CD
+name: CD
 
 on:
   push:
@@ -11,18 +11,9 @@ jobs:
     name: Check Release Tag
     uses: ./.github/workflows/check-release-tag.yml
 
-  ci-job:
-    name: Checks
-    needs: [ check-tag-version-job ]
-    uses: ./.github/workflows/checks.yml
-
   cd-job:
     name: Continuous Delivery
     needs: [ ci-job ]
     uses: ./.github/workflows/build-and-publish.yml
     secrets:
       PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
-
-  metrics:
-    needs: [ ci-job ]
-    uses: ./.github/workflows/report.yml

.github/workflows/checks.yml

@@ -8,8 +8,8 @@ on:
 
 jobs:
 
-  version-check-job:
-    name: Version Check
+  Version-Check:
+    name: Version
     runs-on: ubuntu-latest
 
     steps:
@@ -24,9 +24,9 @@ jobs:
       - name: Check Version(s)
         run: poetry run version-check `poetry run python -c "from noxconfig import PROJECT_CONFIG; print(PROJECT_CONFIG.version_file)"`
 
-  build-documentation-job:
-    name: Build Documentation
-    needs: [ version-check-job ]
+  Documentation:
+    name: Docs
+    needs: [ Version-Check ]
     runs-on: ubuntu-latest
 
     steps:
@@ -40,9 +40,9 @@ jobs:
         run: |
           poetry run python -m nox -s build-docs
 
-  lint-job:
+  Lint:
     name: Linting (Python-${{ matrix.python-version }})
-    needs: [ version-check-job ]
+    needs: [ Version-Check ]
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -68,9 +68,9 @@ jobs:
           path: .lint.txt
           include-hidden-files: true
 
-  type-check-job:
+  Type-Check:
     name: Type Checking (Python-${{ matrix.python-version }})
-    needs: [ version-check-job ]
+    needs: [ Version-Check ]
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -89,9 +89,9 @@ jobs:
       - name: Run type-check
         run: poetry run nox -s type-check
 
-  security-job:
-    name: Security Checking (Python-${{ matrix.python-version }})
-    needs: [ version-check-job ]
+  Security:
+    name: Security Checks (Python-${{ matrix.python-version }})
+    needs: [ Version-Check ]
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -107,7 +107,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Run security
+      - name: Run security linter
         run: poetry run nox -s security
 
       - name: Upload Artifacts
@@ -117,9 +117,9 @@ jobs:
           path: .security.json
           include-hidden-files: true
 
-  tests-job:
+  Tests:
     name: Tests (Python-${{ matrix.python-version }}, Exasol-${{ matrix.exasol-version}})
-    needs: [ build-documentation-job, lint-job, type-check-job ]
+    needs: [ Documentation, Lint, Type-Check, Security]
     runs-on: ubuntu-latest
     env:
       GITHUB_TOKEN: ${{ secrets.ALTERNATIVE_GITHUB_TOKEN ||  secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -8,15 +8,17 @@ on:
       - "main"
       - "master"
   pull_request:
-    types: [ opened, reopened ]
+    types: [opened, reopened]
   schedule:
     # “At 00:00 on every 7th day-of-month from 1 through 31.” (https://crontab.guru)
     - cron: "0 0 1/7 * *"
 
 jobs:
-  ci-job:
-    uses: ./.github/workflows/checks.yml
 
-  metrics:
-    needs: [ ci-job ]
+  CI:
+    uses: ./.github/workflows/merge-gate.yml
+    secrets: inherit
+
+  Metrics:
+    needs: [ CI ]
     uses: ./.github/workflows/report.yml

.github/workflows/merge-gate.yml

@@ -0,0 +1,46 @@
+name: Merge-Gate
+
+on:
+  workflow_call:
+    secrets:
+      ALTERNATIVE_GITHUB_TOKEN:
+        required: false
+
+jobs:
+
+  fast-checks:
+    name: Fast
+    uses: ./.github/workflows/checks.yml
+
+  slow-checks:
+    name: Slow
+    runs-on: ubuntu-latest
+
+    # Even though the environment "manual-approval" will be created automatically,
+    # it still needs to be configured to require interactive review.
+    # See project settings on GitHub (Settings / Environments / manual-approval).
+    environment: manual-approval
+
+    # Replace the steps below with the required actions 
+    # and/or add additional jobs if required
+    # Note: 
+    #   If you add additional jobs, make sure they are added as a requirement 
+    #   to the approve-merge job's input requirements (needs).
+    steps:
+      - name: Tests
+        run: |
+          echo "Slow tests ran successfully"
+
+
+  # This job ensures inputs have been executed successfully.
+  approve-merge:
+    name: Allow Merge 
+    runs-on: ubuntu-latest
+    # If you need additional jobs to be part of the merge gate, add them below
+    needs: [ fast-checks, slow-checks ]
+
+    # Each job requires a step, so we added this dummy step.
+    steps:
+      - name: Approve 
+        run: |
+          echo "Merge Approved"

.github/workflows/report.yml

@@ -8,8 +8,7 @@ on:
 
 jobs:
 
-  report:
-    name: Generate Status Report
+  Report:
     runs-on: ubuntu-latest
     env:
       GITHUB_TOKEN: ${{ secrets.ALTERNATIVE_GITHUB_TOKEN ||  secrets.GITHUB_TOKEN }}

doc/_static/ci-cd-workflow.png

@@ -3,24 +3,26 @@
 ## ✨ Added
 
 * Added cookiecutter-template for creating new project
-
-## 🔩 Internal
-
-* Update depdency constraints
-* Relock dependencies
+* [#246](https://github.com/exasol/python-toolbox/issues/246): Added standard branch protection workflow
 
 ## 🐞 Bug Fixes
 
-* #181 Updated metrics related workflows
-* #225 Fixed broken reference to version file in workflow
+* [#181](https://github.com/exasol/python-toolbox/issues/181): Updated metrics related workflows
+* [#225](https://github.com/exasol/python-toolbox/issues/225): Fixed broken reference to version file in workflow
 * Fixed coverage for empty project
 
 ## ⚒️ Refactorings
 
-* #219: Updated project template configuration
+* [#219](https://github.com/exasol/python-toolbox/issues/219): Updated project template configuration
 * Updated actions/checkout to v4
 
 ## 📚 Documentation
 * Add Python Styleguide
 * Add Issue Guide
 * Updated User Documentation
+
+## 🔩 Internal
+
+* Update depdency constraints
+* Relock dependencies
+

doc/_static/ci-workflow.png

@@ -1,105 +1,45 @@
-Workflows (CI/CD)
-=================
+Github Workflows
+================
 
-Generate CI & CI/CD workflows
------------------------------
-
-The exasol-toolbox simplifies and supports 3 easily maintainable workflows.
-in order to make them work follow the description bellow.
+The exasol-toolbox ships with various GitHub workflows. By default, we suggest installing all of them,
+while the core workflows are:
 
 **Workflows**:
 
 * CI
-    Verifies PR's and regularly checks the project.
+    Verifies PRs and regularly checks the project.
 
-* CI/CD
-    Verifies and publishes releases of the project.
+* CD
+    Publishes releases of the project.
 
 * PR-Merge
-    Validates merges  and updates the documentation.
-
-0. Determine the toolbox version
-++++++++++++++++++++++++++++++++
-One of the snippets bellow, should do the trick:
-
-#.
+    Validates merges and updates the documentation.
 
-    .. code-block:: shell
 
-        poetry show exasol-toolbox
+The toolbox command itself, :code:`tbx`, provides various CLI functions to help you maintain those workflows.
+For further help, run the command :code:`tbx workflow --help`.
 
-#.
-
-    .. code-block:: python
+1. Configure your project
++++++++++++++++++++++++++
 
-        python -c "from exasol.toolbox.version import VERSION;print(VERSION)"
+* Make sure your GitHub project has access to a deployment token for PyPi with the following name: **PYPI_TOKEN**. It should be available to the repository either as an Organization-, Repository-, or Environment-secret.
 
-1. Configure your project
-++++++++++++++++++++++++++
-Make sure your github project has access to a deployment token for PyPi with the following name:  **PYPI_TOKEN**.
-It should be available to the repository either as Organization-, Repository- or Environment- secret.
+* If your CI workflow involves slow or expensive steps you can guard these to be executed only after manual approval. The CI workflow will automaticall create a GitHub environment named :code:`manual-approval`. You only need to add reviewers in (:code:`Settings/Environments/manual-approval`) and move the steps to be guarded into the related section in job :code:`slow-checks` in file :code:`.github/workflows/merge-gate.yml`.
 
-2. Add the standard workflows to your project
-+++++++++++++++++++++++++++++++++++++++++++++
+2. Add all workflows to your project
+++++++++++++++++++++++++++++++++++++
 
 .. code-block:: shell
 
     tbx workflow install all
 
 .. warning::
 
-    If you already have various workflows you may want to run the
-    :code:`update` instead of the :code:`install` command.
-
-CI Workflow
-___________
-
-.. figure:: ../_static/ci-workflow.png
-    :alt: ci-workflow
-
-To enable this workflow, add a file with the name *ci.yml* in your *.github/workflows* folder
-and add the following content:
-
-.. literalinclude:: ../../exasol/toolbox/templates/github/workflows/ci.yml
-    :language: yaml
-
-CI/CD Workflow
-______________
-
-.. attention::
-
-    Requires PYPI token to be available
-
-.. figure:: ../_static/ci-cd-workflow.png
-    :alt: ci-cd-workflow
-
-To enable this workflow, add a file with the name *ci-cd.yml* in your *.github/workflows* folder
-and add the following content:
-
-.. literalinclude:: ../../exasol/toolbox/templates/github/workflows/ci-cd.yml
-    :language: yaml
-
-PR-Merge Workflow
-_________________
-
-.. figure:: ../_static/pr-merge-workflow.png
-    :alt: pr-merge-workflow
-
-To enable this workflow, add a file with the name *pr-merge.yml* in your *.github/workflows* folder
-and add the following content:
-
-.. literalinclude:: ../../exasol/toolbox/templates/github/workflows/pr-merge.yml
-    :language: yaml
+    #. If you already have various workflows, you may want to run the :code:`update` command instead of the :code:`install` command.
 
-In order to make merging to the main branch faster you can skip running the
-tests again in this workflow.
+    #. Some workflows depend on other workflows. Please ensure you have all the required workflows if you do not install all of them.
 
-Before removing the ``ci-job`` from the workflow by please make sure the
-following prerequisites are met, as in some circumstances these tests might be
-the last or even only chance to detect problems.
+3. Update Branch Protection
+++++++++++++++++++++++++++++
 
-* GitHub branch protection for main branch is properly configured.
-* All dependencies are pointing to proper pypi packages in specific versions, i.e. no
-  dependencies to the main branch of other git repositories.
-* Development branches are short-lived and merged to main branch soon after
-  finishing tests in the context of a pull request.
+The best and most maintainable way to have solid branch protection (:code:`Settings/Branches/main`) is to require the workflow :code:`CI / Allow Merge` to pass successfully.