Github Actions: Deploy docusaurus on pull request from Ampersand repo

Problem Definition

The Documentation files and Docusaurus source code reside in two different repositories. The final webpage requires both in order to be deployed.

Depends on

[x] #1323
[x] #1318
[x] #1317

Solution

Refactor the GitHub workflow inside the new repo. The goal of that workflow is to generate a single-page website from the contents of the docs directory in the development branch of Ampersand. The workflow should be triggered any time when there is a new commit/merge/pull request of the development branch of Ampersand. Use github pages to serve this single-page website. Use Docusaurus as a generator.

Tasks

[x] Research: How to combine multiple repositories with Github Actions

Solution

I propose the following solution:

DocuGen contains DeployToPages.yml, a GitHub Action which retrieves the "docs" folders from Ampersand and Prototype and deploys the Docusaurus Website to GitHub Pages.
Ampersand contains triggerDocsUpdate.yml, a GitHub Action which triggers DeployToPages.yml on a push to the development (main) branch when changes are made to the "docs" folder.
Prototype contains triggerDocsUpdate.yml, a GitHub Action which triggers DeployToPages.yml on a push to the development (main) branch when changes are made to the "docs" folder.

Notes

A GitHub Action can be called from an Actions in a different Repository when the target Action contains:

on:
  workflow_dispatch:

This can be done with the following code:

# Workflow which triggers the workflow in DocuGen on changes to "Docs"
name: Trigger Documentation Update

on:
 # Runs on pushes targeting the development branch which contain changes in the "Docs" folder
  push:
    branches:
    - development
    paths:
    - Docs

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    # Trigger the "DeployToPages" workflow in the "DocuGen" repository
      - run: |
          curl -X POST \
          -H "Authorization: Bearer ${{secrets.ACCESS_TOKEN}}" \
          -H "Accept: application/vnd.github.v3+json" \
          https://api.github.com/repos/AmpersandTarski/DocuGen/actions/workflows/DeployToPages.yml/dispatches \
          -d '{"ref": "master"}'

AmpersandTarski / Ampersand