perf: speed up preview builds with pre-built library docs

.github/actions/build-website/action.yml

@@ -34,20 +34,7 @@ runs:
       uses: actions/setup-node@v4
       with:
         node-version-file: ".nvmrc"
-
-    - name: "Checkout 'terraform-aws-components' Repository"
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 1
-        repository: cloudposse/terraform-aws-components
-        ref: main
-        path: tmp/components/terraform-aws-components
-
-    - name: "Setup Python"
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.10'
-        cache: 'pip'
+        cache: 'npm'
 
     # Set same key to restore cache in all jobs
     # Update key once a week - TTL on unused cache is 7 days
@@ -65,56 +52,28 @@ runs:
       with:
         path: |
           .build-harness
-          .cache
         key: ${{ steps.cache-key.outputs.result }}
 
     - name: "Initialize Build Harness"
       shell: bash
       run: |
         make init
 
-    - name: Install Atmos
-      uses: cloudposse/github-action-setup-atmos@v2
-      with:
-        install-wrapper: false
-
-    - name: "Install Python Dependencies"
-      shell: bash
-      run: |
-        pip install -r scripts/docs-collator/requirements.txt
-
-    - name: "Install terraform-docs"
-      uses: jaxxstorm/action-install-gh-release@v1.12.0
-      with:
-        repo: terraform-docs/terraform-docs
-        tag: v0.18.0
-        cache: enable
-
-    - name: Install Atmos
-      uses: cloudposse/github-action-setup-atmos@v2
-      with:
-        install-wrapper: false
-
-    - name: "Render Documentation for Terraform Components"
-      shell: bash
-      env:
-        PUBLIC_REPO_ACCESS_TOKEN: ${{ inputs.repo_access_token }}
-      run: |
-        ./scripts/render-docs-for-components.sh
-
-    - name: "Render Documentation for Terraform Modules"
-      shell: bash
-      env:
-        PUBLIC_REPO_ACCESS_TOKEN: ${{ inputs.repo_access_token }}
-      run: |
-        ./scripts/render-docs-for-modules.sh
-
-    - name: "Render Documentation for GitHub Actions"
+    # Download pre-built library docs from GitHub Release
+    # The library-docs-generate.yml workflow must have run at least once
+    - name: "Download Pre-built Library Docs"
       shell: bash
       env:
-        PUBLIC_REPO_ACCESS_TOKEN: ${{ inputs.repo_access_token }}
+        GH_TOKEN: ${{ inputs.repo_access_token }}
       run: |
-        ./scripts/render-docs-for-github-actions.sh
+        echo "Downloading pre-built library docs from GitHub Release..."
+        gh release download library-docs-latest \
+          --repo ${{ github.repository }} \
+          --pattern "library-docs.tar.gz" \
+          --dir /tmp
+        echo "Extracting library docs..."
+        tar -xzf /tmp/library-docs.tar.gz
+        echo "Library docs downloaded and extracted successfully"
 
     - name: Install Dependencies and Build Website
       shell: bash

.github/workflows/generate-library.yml

@@ -0,0 +1,234 @@
+name: "📚 Generate Library"
+
+on:
+  schedule:
+    - cron: "0 8 * * 1"  # Every Monday at 8am UTC
+  workflow_dispatch:
+  workflow_call:
+  push:
+    branches: [master, main]
+    paths:
+      - 'scripts/docs-collator/**'
+
+# These permissions are needed for creating releases and OIDC
+permissions:
+  id-token: write
+  contents: write
+
+env:
+  AWS_REGION: us-east-2
+  # Use dev account for library docs generation
+  IAM_ROLE_ARN: arn:aws:iam::068007702576:role/cplive-plat-ue2-dev-cloudposse-docs-gha
+  IAM_ROLE_SESSION_NAME: cloudposse-docs-library-docs
+
+concurrency:
+  group: "library-docs-generate"
+  cancel-in-progress: true
+
+jobs:
+  components:
+    name: Components
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ env.AWS_REGION }}
+          role-to-assume: ${{ env.IAM_ROLE_ARN }}
+          role-session-name: ${{ env.IAM_ROLE_SESSION_NAME }}
+
+      - name: "Checkout 'terraform-aws-components' Repository"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+          repository: cloudposse/terraform-aws-components
+          ref: main
+          path: tmp/components/terraform-aws-components
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Install Atmos
+        uses: cloudposse/github-action-setup-atmos@v2
+        with:
+          install-wrapper: false
+
+      - name: Install Python Dependencies
+        run: pip install -r scripts/docs-collator/requirements.txt
+
+      - name: Install terraform-docs
+        uses: jaxxstorm/action-install-gh-release@v1.12.0
+        with:
+          repo: terraform-docs/terraform-docs
+          tag: v0.18.0
+          cache: enable
+
+      - name: Render Documentation for Terraform Components
+        env:
+          PUBLIC_REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+        run: ./scripts/render-docs-for-components.sh
+
+      - name: Upload Components Docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: library-docs-components
+          path: docs/components/library/
+          retention-days: 1
+
+  modules:
+    name: Modules
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ env.AWS_REGION }}
+          role-to-assume: ${{ env.IAM_ROLE_ARN }}
+          role-session-name: ${{ env.IAM_ROLE_SESSION_NAME }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Install Atmos
+        uses: cloudposse/github-action-setup-atmos@v2
+        with:
+          install-wrapper: false
+
+      - name: Install Python Dependencies
+        run: pip install -r scripts/docs-collator/requirements.txt
+
+      - name: Install terraform-docs
+        uses: jaxxstorm/action-install-gh-release@v1.12.0
+        with:
+          repo: terraform-docs/terraform-docs
+          tag: v0.18.0
+          cache: enable
+
+      - name: Render Documentation for Terraform Modules
+        env:
+          PUBLIC_REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+        run: ./scripts/render-docs-for-modules.sh
+
+      - name: Upload Modules Docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: library-docs-modules
+          path: docs/modules/library/
+          retention-days: 1
+
+  github-actions:
+    name: GitHub Actions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v4
+        with:
+          aws-region: ${{ env.AWS_REGION }}
+          role-to-assume: ${{ env.IAM_ROLE_ARN }}
+          role-session-name: ${{ env.IAM_ROLE_SESSION_NAME }}
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Install Atmos
+        uses: cloudposse/github-action-setup-atmos@v2
+        with:
+          install-wrapper: false
+
+      - name: Install Python Dependencies
+        run: pip install -r scripts/docs-collator/requirements.txt
+
+      - name: Install terraform-docs
+        uses: jaxxstorm/action-install-gh-release@v1.12.0
+        with:
+          repo: terraform-docs/terraform-docs
+          tag: v0.18.0
+          cache: enable
+
+      - name: Render Documentation for GitHub Actions
+        env:
+          PUBLIC_REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}
+        run: ./scripts/render-docs-for-github-actions.sh
+
+      - name: Upload GitHub Actions Docs
+        uses: actions/upload-artifact@v4
+        with:
+          name: library-docs-github-actions
+          path: docs/github-actions/library/
+          retention-days: 1
+
+  package-and-release:
+    name: Package and Release
+    needs: [components, modules, github-actions]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Download Components Docs
+        uses: actions/download-artifact@v4
+        with:
+          name: library-docs-components
+          path: docs/components/library/
+
+      - name: Download Modules Docs
+        uses: actions/download-artifact@v4
+        with:
+          name: library-docs-modules
+          path: docs/modules/library/
+
+      - name: Download GitHub Actions Docs
+        uses: actions/download-artifact@v4
+        with:
+          name: library-docs-github-actions
+          path: docs/github-actions/library/
+
+      - name: Create Library Docs Tarball
+        run: |
+          tar -czvf library-docs.tar.gz \
+            docs/components/library \
+            docs/modules/library \
+            docs/github-actions/library
+
+      - name: Delete Existing Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release delete library-docs-latest --yes || true
+          git push origin :refs/tags/library-docs-latest || true
+
+      - name: Create Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create library-docs-latest \
+            --title "Library Docs (Latest)" \
+            --notes "Pre-built library documentation for fast preview builds. Generated $(date -u +'%Y-%m-%d %H:%M:%S UTC')." \
+            --prerelease \
+            library-docs.tar.gz

.github/workflows/website-deploy-preview.yml

@@ -27,14 +27,22 @@ env:
 # These permissions are needed to interact with the GitHub's OIDC Token endpoint
 permissions:
   id-token: write
-  contents: read
+  contents: write
 
 concurrency:
   group: "docs-preview-${{ github.event.pull_request.number }}"
   cancel-in-progress: true
 
 jobs:
+  # Optionally rebuild library docs when 'rebuild-library-docs' label is present
+  generate-library-docs:
+    if: ${{ contains(github.event.pull_request.labels.*.name, 'rebuild-library-docs') }}
+    uses: ./.github/workflows/generate-library.yml
+    secrets: inherit
+
   deploy-preview:
+    needs: generate-library-docs
+    if: ${{ always() && !failure() && !cancelled() }}
     runs-on: ubuntu-latest
 
     environment:

.github/workflows/website-deploy-release.yml

@@ -24,10 +24,15 @@ env:
 # These permissions are needed to interact with the GitHub's OIDC Token endpoint
 permissions:
   id-token: write
-  contents: read
+  contents: write
 
 jobs:
+  generate-library-docs:
+    uses: ./.github/workflows/generate-library.yml
+    secrets: inherit
+
   deploy-release:
+    needs: generate-library-docs
     runs-on: ubuntu-latest
 
     environment: