Add CI/CD pipeline for docs (#1342)

This PR adds the following Github Actions:
* Docs web preview for every pull request
* Format check on pull requests
* Deploy `prod` and `dev`

Additionally, I added a `robots.txt` to prevent indexing our dev docs in
Google. The `robots.txt` will be removed before deploying to `prod`.

In the future we can also add a `sz deploy docs`
(#1346)

.github/workflows/docs_cd.yml

@@ -0,0 +1,60 @@
+# Copyright (c) 2022 Sharezone UG (haftungsbeschränkt)
+# Licensed under the EUPL-1.2-or-later.
+#
+# You may obtain a copy of the Licence at:
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# SPDX-License-Identifier: EUPL-1.2
+
+name: docs-cd
+
+concurrency:
+  # Avoids running multiple deployments at the same time which would cause
+  # conflicts.
+  group: docs-release
+
+on:
+  push:
+    branches:
+      - main
+
+# Set permissions to none.
+#
+# Using the broad default permissions is considered a bad security practice
+# and would cause alerts from our scanning tools.
+permissions: {}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    name: docs-deploy-${{ matrix.environment.flavor }}
+    permissions:
+      checks: write # for FirebaseExtended/action-hosting-deploy
+    strategy:
+      matrix:
+        environment:
+          - flavor: dev
+            projectId: sharezone-debug
+            serviceAccountSecret: FIREBASE_SERVICE_ACCOUNT_SHAREZONE_DEBUG
+          - flavor: prod
+            projectId: sharezone-c2bd8
+            serviceAccountSecret: FIREBASE_HOSTING_PROD_KEY
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+      - name: Install dependencies
+        run: npm install -C docs
+
+      # Our production docs should be indexed by search engines.
+      - name: Remove robots.txt
+        if: ${{ matrix.environment.flavor == 'prod' }}
+        run: rm -f docs/public/robots.txt
+
+      - uses: FirebaseExtended/action-hosting-deploy@v0
+        with:
+          repoToken: "${{ secrets.GITHUB_TOKEN }}"
+          firebaseServiceAccount: "${{ secrets[matrix.environment.serviceAccountSecret] }}"
+          channelId: live
+          entryPoint: "./docs"
+          target: docs
+          projectId: ${{ matrix.environment.projectId }}

.github/workflows/safe_docs_ci.yml

@@ -0,0 +1,89 @@
+# Copyright (c) 2022 Sharezone UG (haftungsbeschränkt)
+# Licensed under the EUPL-1.2-or-later.
+#
+# You may obtain a copy of the Licence at:
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# SPDX-License-Identifier: EUPL-1.2
+
+# This workflow handles the CI for the docs.
+#
+# Therefore, it's only triggered on pull requests that make changes to the It
+# only contains jobs that don't require any secrets. The jobs that require
+# secrets are handled in the "unsafe_docs_ci.yml" workflow.
+
+name: safe-docs-ci
+
+concurrency:
+  group: safe-docs-ci-${{ github.head_ref }}
+  # In order to conserve the use of GitHub Actions, we cancel the running action
+  # of the previous commit. This means that if you first commit "A" and then
+  # commit "B" to the pull request a few minutes later, the workflow for commit
+  # "A" will be cancelled.
+  cancel-in-progress: true
+
+on:
+  # Triggers the workflow on pull request events
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      # It's important to trigger this workflow again when the pull is changing
+      # from a draft pull request to a ready for review pull request.
+      #
+      # Some jobs are skipped when the pull request is a draft. Therefore, we
+      # need to trigger these jobs again when the pull request is changing to
+      # ready for review.
+      - ready_for_review
+      # Retrigger the workflow when label has been add to run the CI when the
+      # "safe to test" label is added.
+      - labeled
+  merge_group:
+    types:
+      - checks_requested
+
+# Set permissions to none.
+#
+# Using the broad default permissions is considered a bad security practice
+# and would cause alerts from our scanning tools.
+permissions: {}
+
+jobs:
+  # We can't use the official "paths" filter because it has no support for merge
+  # groups and we would need some kind of fallback CI when a check is required
+  # but ignored because of the path filter.
+  #
+  # See:
+  # * https://github.com/community/community/discussions/45899 (merge groups)
+  # * https://github.com/github/docs/commit/4364076e0fb56c2579ae90cd048939eaa2c18954
+  #   (workaround for required checks with path filters)
+  changes:
+    runs-on: ubuntu-22.04
+    outputs:
+      changesFound: ${{ steps.filter.outputs.changesFound }}
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - uses: AurorNZ/paths-filter@3b1f3abc3371cca888d8eb03dfa70bc8a9867629
+        id: filter
+        with:
+          filters: |
+            changesFound:
+              # We only build and deploy a new version, when a user relevant files
+              # changed.
+              - "docs/**"
+              # We trigger also this workflow, if this workflow is changed, so that new
+              # changes will be applied.
+              - ".github/workflows/safe_docs_ci.yml"
+
+  format:
+    needs: changes
+    if: ${{ needs.changes.outputs.changesFound == 'true'}}
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+      - name: Install Prettier
+        run: npm install --global [email protected]
+
+      - run: ./bin/check_format_markdown_files.sh

.github/workflows/unsafe_docs_ci.yml

@@ -0,0 +1,144 @@
+# Copyright (c) 2022 Sharezone UG (haftungsbeschränkt)
+# Licensed under the EUPL-1.2-or-later.
+#
+# You may obtain a copy of the Licence at:
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# SPDX-License-Identifier: EUPL-1.2
+
+# This workflow handles the CI for the docs.
+#
+# Therefore, it's only triggered on pull requests that make changes to the
+# docs. It only contains jobs that require secrets. The jobs that don't
+# require secrets are handled in the "safe_docs_ci.yml" workflow.
+
+name: unsafe-docs-ci
+
+concurrency:
+  group: unsafe-docs-ci-${{ github.head_ref }}
+  # In order to conserve the use of GitHub Actions, we cancel the running action
+  # of the previous commit. This means that if you first commit "A" and then
+  # commit "B" to the pull request a few minutes later, the workflow for commit
+  # "A" will be cancelled.
+  cancel-in-progress: true
+
+on:
+  # Triggers the workflow on pull request events
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      # It's important to trigger this workflow again when the pull is changing
+      # from a draft pull request to a ready for review pull request.
+      #
+      # Some jobs are skipped when the pull request is a draft. Therefore, we
+      # need to trigger these jobs again when the pull request is changing to
+      # ready for review.
+      - ready_for_review
+      # Retrigger the workflow when label has been add to run the CI when the
+      # "safe to test" label is added.
+      - labeled
+  merge_group:
+    types:
+      - checks_requested
+
+# Set permissions to none.
+#
+# Using the broad default permissions is considered a bad security practice
+# and would cause alerts from our scanning tools.
+permissions: {}
+
+jobs:
+  # It's important that we run this job first, because we need to remove the
+  # "safe to test" label when the PR comes from a fork in order to ensure that
+  # every change is reviewed for security implications.
+  remove-safe-to-build-label:
+    runs-on: ubuntu-22.04
+    permissions:
+      # Required by the remove-safe-to-test-label action
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Remove "safe to test" label, if PR is from a fork
+        uses: SharezoneApp/remove-safe-to-test-label@91b378205db41bb08dde8e4c4f2685847eb3d168
+
+  # We can't use the official "paths" filter because it has no support for merge
+  # groups and we would need some kind of fallback CI when a check is required
+  # but ignored because of the path filter.
+  #
+  # See:
+  # * https://github.com/community/community/discussions/45899 (merge groups)
+  # * https://github.com/github/docs/commit/4364076e0fb56c2579ae90cd048939eaa2c18954
+  #   (workaround for required checks with path filters)
+  changes:
+    needs: remove-safe-to-build-label
+    runs-on: ubuntu-22.04
+    outputs:
+      changesFound: ${{ steps.filter.outputs.changesFound }}
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with:
+          # Because we are using the "pull_request_target" event, we need to
+          # checkout the PR head commit instead of the merge commit.
+          ref: ${{ github.event.pull_request.head.sha }}
+      - uses: AurorNZ/paths-filter@3b1f3abc3371cca888d8eb03dfa70bc8a9867629
+        id: filter
+        with:
+          filters: |
+            changesFound:
+              # We only build and deploy a new version, when a user relevant files
+              # changed.
+              - "docs/**"
+              # We trigger also this workflow, if this workflow is changed, so that new
+              # changes will be applied.
+              - ".github/workflows/unsafe_docs_ci.yml"
+
+  # We are building for every PR a web preview, which will be deployed to
+  # Firebase Hosting. The link to the website will posted as comment (like:
+  # https://github.com/SharezoneApp/sharezone-app/pull/119#issuecomment-1030012299).
+  #
+  # The previews are helping reviewer and other users to quickly view the
+  # changes in a compiled version.
+  #
+  # A link to a preview expires after 3 days.
+  #
+  # Required steps to set this up:
+  # 1. Run "firebase init hosting:github"
+  # 2. Enable "Firebase Hosting API" in Google Cloud project
+  # 3. Write GitHub action job
+  # 4. Adjust website restrictions for Firebase Key "Sharezone Web Key".
+  web-preview:
+    needs: changes
+    if: ${{ github.event_name == 'pull_request_target' && needs.changes.outputs.changesFound == 'true'}}
+    runs-on: ubuntu-22.04
+    permissions:
+      pull-requests: write # for FirebaseExtended/action-hosting-deploy to comment on PRs
+      checks: write # for FirebaseExtended/action-hosting-deploy to comment on PRs (without write permissions for checks the action doesn't post a comment to the PR, we don't know why)
+    steps:
+      - name: Ensure PR has "safe to test" label, if PR is from a fork
+        uses: SharezoneApp/verify-safe-to-test-label@c1059d43fc918756660a700ca6d08e445ff314a2
+
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+        with:
+          # Because we are using the "pull_request_target" event, we need to
+          # checkout the PR head commit instead of the merge commit.
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Install dependencies
+        run: npm install -C docs/
+
+      - name: Deploy to Firebase Hosting
+        uses: FirebaseExtended/action-hosting-deploy@120e124148ab7016bec2374e5050f15051255ba2
+        with:
+          repoToken: ${{ secrets.GITHUB_TOKEN }}
+          firebaseServiceAccount: ${{ secrets.FIREBASE_SERVICE_ACCOUNT_SHAREZONE_DEBUG }}
+          projectId: sharezone-debug
+          entryPoint: "./docs"
+          # The expiration date shouldn't be too high, because if we open a lot
+          # of pull requests, we will run out of quota (we get 429 errors).
+          expires: "3d"
+          target: "docs"
+        env:
+          # Required to deploy Next.js applications to Firebase Hosting
+          FIREBASE_CLI_EXPERIMENTS: webframeworks

bin/check_format_markdown_files.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+# Copyright (c) 2023 Sharezone UG (haftungsbeschränkt)
+# Licensed under the EUPL-1.2-or-later.
+#
+# You may obtain a copy of the Licence at:
+# https://joinup.ec.europa.eu/software/page/eupl
+#
+# SPDX-License-Identifier: EUPL-1.2
+
+script_dir=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+get_cmd="$script_dir/source_of_truth/get_sot_cmd.sh"
+
+check_format_markdown_files=$($get_cmd check_format_markdown_files)
+eval $"($check_format_markdown_files)"

docs/.firebaserc

@@ -1,5 +1,22 @@
 {
   "projects": {
-    "default": "sharezone-c2bd8"
+    "prod": "sharezone-c2bd8",
+    "dev": "sharezone-debug"
+  },
+  "targets": {
+    "sharezone-debug": {
+      "hosting": {
+        "docs": [
+          "sharezone-docs-dev"
+        ]
+      }
+    },
+    "sharezone-c2bd8": {
+      "hosting": {
+        "docs": [
+          "sharezone-docs-prod"
+        ]
+      }
+    }
   }
-}
+}

docs/firebase.json

@@ -1,6 +1,6 @@
 {
   "hosting": {
-    "site": "sharezone-docs-prod",
+    "target": "docs",
     "source": ".",
     "ignore": [
       "firebase.json",

docs/public/robots.txt

@@ -0,0 +1,6 @@
+# Disallow all robots from indexing non production docs. Otherwise, our users
+# would find the dev docs in search results.
+# 
+# When deploying to production, remove this file before building the site.
+User-agent: *
+Disallow: /