publish.yml

# .github/workflows/publish.yml
#
# Copyright © 2025-2026 Network Pro Strategies (Network Pro™)
# SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
# This file is part of Network Pro

# ------------------------------------------------------------------------------
# SECURITY MODEL: Principle of Least Privilege for GITHUB_TOKEN
#
# This workflow follows GitHub’s security-hardening guidance by using
# `permissions: {}` at the top level and explicitly declaring the minimum
# required permissions per job.
#
# Rationale:
# - The `build` job only requires read access to fetch repository contents and
#   artifacts (no write operations).
# - The `publish-npm` job uses a scoped NPM access token (`NPM_NETPRO`) for
#   authentication and requires no GitHub write permissions.
# - The `publish-gpr` job requires `packages: write` to push to GitHub Packages,
#   but no other privileges (no Pages, Actions, or OIDC permissions).
#
# This configuration:
#   • Prevents over-privileged workflow tokens.
#   • Ensures isolation between build and publish jobs.
#   • Limits the impact of a compromised job or dependency.
#
# References:
#   - GitHub Docs: https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
#   - GitHub Blog: "Security Hardening for GitHub Actions"
# ------------------------------------------------------------------------------

name: Publish to Registries

on:
  release:
    types: [created]
  workflow_dispatch:

permissions:
  actions: read
  contents: read
  packages: write

# Allow one concurrent deployment
concurrency:
  group: 'build-and-publish'
  cancel-in-progress: true

jobs:
  check-codeql:
    uses: ./.github/workflows/check-codeql.yml

  build:
    needs: check-codeql
    runs-on: ubuntu-24.04
    env:
      ENV_MODE: ci

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - name: Set up Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Upgrade npm
        run: |
          corepack enable
          npm install -g npm@11.7.0

      - name: Install Node.js dependencies
        run: npm ci

      # MkDocs Integration
      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version-file: '.python-version'
          cache: 'pip'

      - name: Install Python dependencies
        run: pip install -r requirements.txt

      - name: Build MkDocs documentation
        run: mkdocs build

      # Remove build artifacts to avoid publishing them
      - name: Clean build directory
        run: rm -rf build/

      # Create Git archive of version-controlled files
      - name: Create clean source archive
        run: git archive --format=tar.gz --output=clean-source.tar.gz HEAD

      - name: Upload source archive
        uses: actions/upload-artifact@v6
        with:
          name: clean-source
          path: clean-source.tar.gz

  publish-npm:
    needs: build
    runs-on: ubuntu-24.04
    env:
      ENV_MODE: ci

    steps:
      - name: Download clean source archive
        uses: actions/download-artifact@v7
        with:
          name: clean-source
          path: ./

      - name: Extract source archive
        run: tar -xzf clean-source.tar.gz

      - name: Remove extracted source archive
        run: rm clean-source.tar.gz

      - name: Set up Node.js for npmjs
        uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: https://registry.npmjs.org/
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Set up Git user
        run: |
          git config --global user.email "github@sl.neteng.cc"
          git config --global user.name "SunDevil311"

      - name: Publish package to npmjs
        run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_NETPRO }}

  publish-gpr:
    needs: build
    runs-on: ubuntu-24.04
    env:
      ENV_MODE: ci

    steps:
      - name: Download clean source archive
        uses: actions/download-artifact@v7
        with:
          name: clean-source
          path: ./

      - name: Extract source archive
        run: tar -xzf clean-source.tar.gz

      - name: Remove extracted source archive
        run: rm clean-source.tar.gz

      - name: Set up Node.js for GPR
        uses: actions/setup-node@v6
        with:
          node-version: 24
          registry-url: https://npm.pkg.github.com/
          cache: npm
          cache-dependency-path: package-lock.json

      - name: Set up Git user
        run: |
          git config --global user.email "github@sl.neteng.cc"
          git config --global user.name "SunDevil311"

      - name: Update package name for GPR
        run: |
          sed -i 's/"name": "[^"]*"/"name": "@netwk-pro\/docs"/' package.json

      - name: Publish package to GPR
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}