deploy-lab.yml

name: Deploy Labspace labs

# Reusable workflow that validates a repo's labs, assembles a static site by
# overlaying them onto the prebuilt runtime image's payload, generates the
# labs.json catalog, and publishes to GitHub Pages. A lab author's repo calls it
# in one step:
#
#   jobs:
#     deploy:
#       uses: dockersamples/simspace/.github/workflows/deploy-lab.yml@main
#       with:
#         runtime-tag: "1"        # pin to a released version
#       permissions:
#         contents: read
#         pages: write
#         id-token: write
#
# Labs are loaded at runtime, so no app rebuild is needed — the site is just the
# runtime image's static files with the author's labs/ swapped in and a freshly
# generated labs.json. One lab is entered directly; several show a landing page.

on:
  workflow_call:
    inputs:
      labs-dir:
        description: "Path to the labs directory (contains labs/<id>/labspace.yaml)."
        type: string
        default: "labs"
      runtime-image:
        description: "Runtime image the site is based on."
        type: string
        default: "dockersamples/simspace"
      authoring-image:
        description: "Authoring image used to validate labs + generate the catalog."
        type: string
        default: "dockersamples/simspace-authoring"
      runtime-tag:
        description: "Image tag for BOTH images. Pin to a version for stable labs."
        type: string
        default: "latest"
      pulse-endpoint:
        description: "Base URL of the pulse presence/analytics backend. Set to
          enable tracking for all labs (opt out per lab with `tracking: false`);
          leave empty to disable tracking entirely."
        type: string
        default: ""
      title:
        description: "Deployment-wide site title, shown on the landing page and
          browser tab in place of the \"Labspace\" default (e.g. \"Acme
          Labs\"). Leave empty to keep the default."
        type: string
        default: ""

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Validate labs
        # Validates every lab under labs/ and fails if none are found (e.g. a
        # single-lab repo not yet moved to labs/<id>/).
        run: |
          docker run --rm \
            -v "${{ github.workspace }}/${{ inputs.labs-dir }}:/labs:ro" \
            "${{ inputs.authoring-image }}:${{ inputs.runtime-tag }}" \
            npm run validate-lab -- /labs

  build:
    needs: validate
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Assemble static site (runtime payload + these labs + catalog)
        run: |
          set -euo pipefail
          image="${{ inputs.runtime-image }}:${{ inputs.runtime-tag }}"
          docker pull "$image"
          cid="$(docker create "$image")"
          mkdir -p site
          docker cp "$cid":/usr/share/nginx/html/. site/
          docker rm "$cid"
          # Replace the runtime image's sample labs + catalog with this repo's.
          rm -rf site/labs site/labs.json
          mkdir -p site/labs
          cp -R "${{ inputs.labs-dir }}/." site/labs/
          # Generate labs.json for these labs (from each labspace.yaml).
          docker run --rm \
            -v "${{ github.workspace }}:/work" \
            "${{ inputs.authoring-image }}:${{ inputs.runtime-tag }}" \
            npm run generate-catalog -- "/work/${{ inputs.labs-dir }}" /work/site/labs.json
      - name: Configure deployment settings (config.json)
        # The runtime image ships a dev config.json (localhost tracking, no
        # title). Replace it with this deployment's settings, or remove it
        # entirely when neither is set.
        env:
          PULSE_ENDPOINT: ${{ inputs.pulse-endpoint }}
          SITE_TITLE: ${{ inputs.title }}
        run: |
          set -euo pipefail
          json='{}'
          if [ -n "${PULSE_ENDPOINT}" ]; then
            json=$(jq -n --argjson base "$json" --arg endpoint "$PULSE_ENDPOINT" \
              '$base + {tracking: {endpoint: $endpoint, presence: true, identity: "optional-name"}}')
            echo "Tracking enabled → ${PULSE_ENDPOINT}"
          else
            echo "No pulse-endpoint set; tracking disabled."
          fi
          if [ -n "${SITE_TITLE}" ]; then
            json=$(jq -n --argjson base "$json" --arg title "$SITE_TITLE" '$base + {title: $title}')
            echo "Site title set → ${SITE_TITLE}"
          fi
          if [ "$json" != '{}' ]; then
            echo "$json" > site/config.json
          else
            rm -f site/config.json
          fi
      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0