Build docs preview and production builds in GitHub CI

.github/change_filters.yml

@@ -0,0 +1,5 @@
+docs:
+  - 'docs/**/*'
+  - 'changelog/*'
+  - 'CHANGELOG.mdx'
+  - 'Makefile'

.github/workflows/documentation.yml

@@ -4,23 +4,125 @@ on:
   push:
     branches:
     - 'main'
+    - 'documentation'
     tags:
     - '**'
+  pull_request:
 
 # SECRETS
 # - GH_DOCS_WRITE_KEY: generated locally, added to github repo (public key)
 #                    `ssh-keygen -t rsa -b 4096 -C "Github CI Docs Key" -N "" -f key`
 # - GITHUB_TOKEN: (default, from github actions)
+# - NETLIFY_AUTH_TOKEN: an access token to use when authenticating commands on Netlify
+# - NETLIFY_SITE_ID: the API ID of the Netlify site for the docs
+# - SLACK_ALERTS_CHANNEL_ID: id of Slack channel to send alerts to
 
 env:
   DOCS_FOLDER: docs
   DOCS_BRANCH: documentation
 
 jobs:
-  docs:
-    name: Build Docs
+  changes:
+    name: Check for file changes
     runs-on: ubuntu-latest
-    if: github.repository == 'RasaHQ/rasa-sdk'  # don't run this for main branches of forks, would fail anyways
+    # don't run this for main branches of forks; only on pull request (not needed elsewhere)
+    if: github.repository == 'RasaHQ/rasa-sdk' && github.event_name == 'pull_request'
+    outputs:
+      # Both of the outputs below are strings but only one exists at any given time
+      docs: ${{ steps.changed-files.outputs.docs || steps.run-all.outputs.docs }}
+    steps:
+      - uses: actions/checkout@v2
+      - uses: RasaHQ/pr-changed-files-filter@c4f7116a04b8a4596313469429e2ad235f59d9c4
+        # Run the normal filters if the all-tests-required label is not set
+        id: changed-files
+        if: contains(github.event.pull_request.labels.*.name, 'status:all-tests-required') == false
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          filters: .github/change_filters.yml
+      - name: Set all filters to true if all tests are required
+        # Set all filters to true if the all-tests-required label is set
+        # Bypasses all the change filters in change_filters.yml and forces all outputs to true
+        id: run-all
+        if: contains(github.event.pull_request.labels.*.name, 'status:all-tests-required')
+        run: |
+          echo "::set-output name=docs::true"
+
+  evaluate_release_tag:
+    name: Evaluate release tag
+    runs-on: ubuntu-latest
+    # don't run this for main branches of forks, would fail anyways
+    if: github.repository == 'RasaHQ/rasa-sdk' && github.ref != 'refs/heads/documentation' && github.event_name != 'pull_request'
+    outputs:
+      build_docs: ${{ steps.check_tag.outputs.build_docs }}
+
+    steps:
+    - name: Checkout git repository 🕝
+      uses: actions/checkout@v2
+
+    - name: Check if tag version is equal or higher than the latest tagged Rasa version
+      id: rasa_sdk_get_version
+      run: |
+        # Get latest tagged Rasa SDK version
+        git fetch --depth=1 origin "+refs/tags/*:refs/tags/*"
+        # Fetch branch history
+        git fetch --prune --unshallow
+        LATEST_TAGGED_NON_ALPHA_RASA_SDK_VERSION=$(git tag | sort -r -V | grep -E "^[0-9.]+$" | head -n1)
+
+        echo "LATEST_TAGGED_NON_ALPHA_RASA_SDK_VERSION=${LATEST_TAGGED_NON_ALPHA_RASA_SDK_VERSION}" >> $GITHUB_ENV
+
+        # Return 'true' if tag version is equal or higher than the latest tagged Rasa version
+        IS_LATEST_VERSION=$((printf '%s\n%s\n' "${LATEST_TAGGED_NON_ALPHA_RASA_SDK_VERSION}" "$TAG_NAME" \
+          | sort -V -C && echo true || echo false) || true)
+
+
+        if [[ "${IS_LATEST_VERSION}" == "true" && "$TAG_NAME" =~ ^[0-9.]+$ ]]; then
+          echo "::set-output name=is_latest_version::true"
+        else
+          echo "::set-output name=is_latest_version::false"
+        fi
+
+
+    # MAJOR.MINOR.MICRO(PATCH)
+    # docs are built on every minor tag for the latest major (when 3.0 is out, the latest major is 3.0)
+    # (technically it'll be always the latest version)
+    #
+    # docs are built on every micro tag for the latest minor of
+    # - the latest major (when 3.0 is out, the latest major is 3.0)
+    # - the previous major (when 3.0 is out, the previous major is 2.0, the latest minor on this version being 2.8)
+    - name: Check if it's a micro tag for the latest minor
+      if: env.IS_TAG_BUILD == 'true' || env.IS_MAIN_BRANCH == 'true'
+      id: check_tag
+      run: |
+        IS_LATEST_VERSION=${{ steps.rasa_sdk_get_version.outputs.is_latest_version }}
+
+        # the latest major (when 3.0 is out, the latest major is 3.0)
+        # build docs on push to the main branch
+        if [[ "${IS_LATEST_VERSION}" == "true" || "${IS_MAIN_BRANCH}" == "true" ]]; then
+          echo "::set-output name=build_docs::true"
+          exit 0
+        fi
+
+        # the previous major (when 3.0 is out, the previous major is 2.0, the latest minor on this version being 2.8)
+        CURRENT_MAJOR_VERSION=$(echo ${LATEST_TAGGED_NON_ALPHA_RASA_SDK_VERSION} | awk -F\. '{print $1}')
+        PREVIOUS_MAJOR_LATEST_VERSION=$(git tag | sort -r -V | grep -E "^[0-9.]+$" | grep -vE "^${CURRENT_MAJOR_VERSION}" | head -n1)
+
+        # Return 'true' if tag version is equal or higher than the latest previous major version
+        IS_PREVIOUS_MAJOR_LATEST_VERSION=$((printf '%s\n%s\n' "${PREVIOUS_MAJOR_LATEST_VERSION}" "$TAG_NAME" \
+          | sort -V -C && echo true || echo false) || true)
+
+        if [[ "${IS_PREVIOUS_MAJOR_LATEST_VERSION}" == "true" ]]; then
+          echo "::set-output name=build_docs::true"
+          exit 0
+        fi
+
+        echo "::set-output name=build_docs::false"
+
+  prebuild_docs:
+    name: Prebuild Docs
+    runs-on: ubuntu-latest
+    needs: [ evaluate_release_tag ]
+    # don't run this for main branches of forks, would fail anyways
+    if: github.repository == 'RasaHQ/rasa-sdk' && needs.evaluate_release_tag.outputs.build_docs == 'true' && github.ref != 'refs/heads/documentation' && github.event_name != 'pull_request'
 
     steps:
     - name: Checkout git repository 🕝
@@ -72,7 +174,7 @@ jobs:
       with:
         ssh-private-key: ${{ secrets.GH_DOCS_WRITE_KEY }}
 
-    - name: Build & Publish Docs 🏃‍♀️
+    - name: Push docs to documentation branch 🏃‍♀️
       env:
         TMP_DOCS_FOLDER: /tmp/documentation-${{ github.run_id }}
         TMP_SSH_KEY_PATH: /tmp/docs_key
@@ -82,3 +184,137 @@ jobs:
         git remote set-url --push origin "[email protected]:${{github.repository}}"
 
         ./scripts/push_docs_to_branch.sh
+
+    - name: Notify slack on failure
+      if: failure()
+      env:
+        SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+      uses: voxmedia/github-action-slack-notify-build@212e9f7a9ca33368c8dd879d6053972128258985  # v1.5.0
+      with:
+        channel_id: ${{ secrets.SLACK_ALERTS_CHANNEL_ID }}
+        status: FAILED
+        color: warning
+
+  preview_docs:
+    name: Preview Docs
+    runs-on: ubuntu-latest
+    needs: [ changes ]
+    # don't run this for main branches of forks; only run on pull requests
+    if: github.repository == 'RasaHQ/rasa-sdk' && github.event_name == 'pull_request'
+
+    steps:
+    - name: Checkout git repository 🕝
+      if: needs.changes.outputs.docs == 'true'
+      uses: actions/checkout@v2
+
+    - name: Set up Python 3.7 🐍
+      if: needs.changes.outputs.docs == 'true'
+      uses: actions/setup-python@dc73133d4da04e56a135ae2246682783cc7c7cb6  # v2.2.2
+      with:
+        python-version: 3.7
+
+    - name: Set up Node 12.x 🦙
+      if: needs.changes.outputs.docs == 'true'
+      uses: actions/[email protected]
+      with:
+        node-version: '12.x'
+
+    - name: Read Poetry Version 🔢
+      if: needs.changes.outputs.docs == 'true'
+      run: |
+        echo "POETRY_VERSION=$(scripts/poetry-version.sh)" >> $GITHUB_ENV
+      shell: bash
+
+    - name: Install poetry 🦄
+      if: needs.changes.outputs.docs == 'true'
+      uses: Gr1N/setup-poetry@v7
+      with:
+        poetry-version: ${{ env.POETRY_VERSION }}
+
+    - name: Load Poetry Cached Libraries ⬇
+      if: needs.changes.outputs.docs == 'true'
+      uses: actions/cache@v1
+      with:
+        path: ~/.cache/pypoetry/virtualenvs
+        key: ${{ runner.os }}-poetry-${{ env.POETRY_VERSION }}-3.7-non-full-${{ hashFiles('**/poetry.lock') }}-${{ secrets.POETRY_CACHE_VERSION }}
+        restore-keys: ${{ runner.os }}-poetry-3.7-non-full
+
+    - name: Load Yarn Cached Packages ⬇
+      if: needs.changes.outputs.docs == 'true'
+      uses: actions/cache@v1
+      with:
+        path: docs/node_modules
+        key: ${{ runner.os }}-yarn-12.x-${{ hashFiles('docs/yarn.lock') }}
+        restore-keys: ${{ runner.os }}-yarn-12.x
+
+    - name: Install Dependencies 📦
+      if: needs.changes.outputs.docs == 'true'
+      run: make install install-docs
+
+    - name: Pre-build Docs 🧶
+      if: needs.changes.outputs.docs == 'true'
+      run: make prepare-docs
+
+    - name: Preview draft build 🔬
+      if: needs.changes.outputs.docs == 'true'
+      id: preview_draft_build
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+        DOCS_SITE_BASE_URL: /docs/action-server
+        PULL_REQUEST_NUMBER: ${{ github.event.pull_request.number }}
+      run: |
+        make preview-docs
+        DEPLOY_URL="https://$PULL_REQUEST_NUMBER--rasahq-docsv2-rasa-sdk.netlify.app${DOCS_SITE_BASE_URL}"
+        echo "::set-output name=preview_url::$DEPLOY_URL"
+
+    - name: Create a comment link to docs preview
+      if: needs.changes.outputs.docs == 'true'
+      uses: RasaHQ/create-comment@v1
+      with:
+        mode: 'delete-previous'
+        id: comment_docs_previews
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        body: |
+          🚀 A preview of the docs have been deployed at the following URL: ${{ steps.preview_draft_build.outputs.preview_url }}
+
+  publish_docs:
+    name: Publish Docs
+    runs-on: ubuntu-latest
+    # don't run this for main branches of forks; only run on documentation branch
+    if: github.repository == 'RasaHQ/rasa-sdk' && github.ref == 'refs/heads/documentation'
+
+    steps:
+    - name: Checkout git repository 🕝
+      uses: actions/checkout@v2
+
+    - name: Set up Node 12.x 🦙
+      uses: actions/[email protected]
+      with:
+        node-version: '12.x'
+
+    - name: Load Yarn Cached Packages ⬇
+      uses: actions/cache@v1
+      with:
+        path: docs/node_modules
+        key: ${{ runner.os }}-yarn-12.x-${{ hashFiles('docs/yarn.lock') }}
+        restore-keys: ${{ runner.os }}-yarn-12.x
+
+    - name: Install Dependencies 📦
+      run: make install-docs
+
+    - name: Publish production build ✅
+      env:
+        NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      run: make publish-docs
+
+    - name: Notify slack on failure
+      if: failure()
+      env:
+        SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+      uses: voxmedia/github-action-slack-notify-build@212e9f7a9ca33368c8dd879d6053972128258985  # v1.5.0
+      with:
+        channel_id: ${{ secrets.SLACK_ALERTS_CHANNEL_ID }}
+        status: FAILED
+        color: warning

Makefile

@@ -78,6 +78,12 @@ test-docs: generate-pending-changelog docs
 livedocs:
 	cd docs/ && poetry run yarn start
 
+preview-docs:
+	cd docs/ && yarn build && yarn deploy-preview --alias=${PULL_REQUEST_NUMBER} --message="Preview for Pull Request #${PULL_REQUEST_NUMBER}"
+
+publish-docs:
+	cd docs/ && yarn build && yarn deploy
+
 release:
 	poetry run python scripts/release.py
 

docs/package.json

@@ -11,6 +11,8 @@
     "pre-build": "yarn copy-md-files && yarn variables && yarn included-sources && yarn program-outputs",
     "build": "docusaurus build --out-dir build/docs/action-server",
     "serve": "netlify dev --dir=build --port=5002",
+    "deploy-preview": "netlify deploy --dir=build",
+    "deploy": "netlify deploy --dir=build --prod",
     "swizzle": "docusaurus swizzle",
     "new-version": "docusaurus docs:version",
     "variables": "node scripts/compile_variables.js",