Skip to main content
Version: 1.0

🌉 Deployment Workflows

Select a workflow template to automate the delivery of your documentation from your source repository to its public or private hosting target.

Available Workflow Templates​

1. GitLab ➡️ GitHub (The Bridge)​

Category: Cross-Platform Deployment

Best for: Private development on GitLab with public hosting on GitHub Pages. This "Hybrid" workflow is the heart of the cross-platform philosophy. It allows you to maintain your "Source of Truth" and private CI/CD variables in GitLab while leveraging the global reach and simplicity of GitHub Pages for your public documentation.

  • Logic: Automated mirroring and force-pushing to the gh-pages branch.
  • Security: Utilizes GitLab Protected Variables for GITHUB_TOKEN safety.
  • Status: [Pending Technical Details]
image: node:20-alpine
stages: [build, deploy]

build-job:
  stage: build
  script:
    - cd website && npm ci && npm run build
  artifacts:
    paths: [website/build/]

deploy-job:
  stage: deploy
  image: { name: alpine/git, entrypoint: [""] }
  script:
    - cd website/build
    - git init
    - git config user.name "GitLab CI"
    - git config user.email "ci@gitlab.com"
    - git remote add github "https://x-access-token:${GITHUB_TOKEN}@${GITHUB_REPO_URL}"
    - git add .
    - git commit -m "Deploy from GitLab [skip ci]"
    - git push -f github HEAD:gh-pages
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

This workflow requires a secure handshake between your private GitLab source and your public GitHub target.

  • GitLab Settings (Settings > CI/CD > Variables)

    • GITHUB_TOKEN:
      • A Personal Access Token (PAT) from your GitHub account.
      • Permissions needed: repo scope (for classic tokens) or Contents: Write (for fine-grained tokens).
      • Security: Set as Masked and Protected.
    • GITHUB_REPO_URL: The destination URL. Format: github.com (Do not include https://).

  • GitHub Settings (Settings > Pages)

    • Build and deployment:
      • Set "Source" to Deploy from a branch.
      • Branch: Select gh-pages and folder / (root).

2. Pure GitHub Actions​

Category: Native Deployment

Best for: Projects hosted and developed entirely within the GitHub ecosystem. A streamlined, native approach using GitHub Actions. This template removes the need for cross-platform tokens and provides an "all-in-one" solution for repositories that reside permanently on GitHub.

  • Logic: Native Action triggered on push to the main branch.
  • Security: Leverages built-in GITHUB_TOKEN permissions.
  • Status: [Pending Technical Details]
name: Deploy to GitHub Pages
on:
  push:
    branches:
      - main

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

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

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: website/package-lock.json

      - name: Install dependencies
        run: npm ci

      - name: Build website
        run: cd website && npm ci && npm run build

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: website/build

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Because the source and target are on the same platform, authentication is handled automatically.

  • GitHub Settings (Settings > Actions > General)

    Workflow permissions: Ensure Read and write permissions is selected so the Action can push to the gh-pages branch.

  • GitHub Settings (Settings > Pages)

    Build and deployment: Set "Source" to GitHub Actions. The provided template will handle the rest.

3. Pure GitLab Pages​

Category: Native Deployment

Best for: Internal documentation or projects staying within the GitLab ecosystem. This template is optimized for repositories that prefer to keep their hosting and source code under one roof on GitLab. It is ideal for internal company documentation or projects where a public GitHub mirror is not required.

  • Logic: Standard pages job using the .gitlab-ci.yml framework.
  • Optimization: Automatically swaps deployment URLs from github.io to gitlab.io.
  • Status: [Pending Technical Details]
image: node:20-alpine
pages:
  stage: deploy
  script:
    - cd website
    - npm ci
    - npm run build
    - mv build ../public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

This is a self-contained "Modular Architecture" setup within a single platform.

  • GitLab Settings (Settings > Pages)

    Force HTTPS: Recommended to be Enabled.

    Unique Domain: Once the first pipeline succeeds, your site will be available at https://username.gitlab.io.

  • GitLab Settings (Build > Pipelines)

    No external tokens are required. The built-in CI_JOB_TOKEN handles the internal deployment.

🏗️ Technical Architecture​

All workflows are built on the Modular Architecture and Standardization pillars, ensuring:

  • Uniformity: Consistent build environments across all platforms.
  • Safety: Integrated "Pre-flight" checks to prevent accidental overwrites.
  • Cleanliness: Automated cleanup of build artifacts after successful deployment.