icp-cli/.github/workflows/docs.yml at 463b69ed225c03315283cc47261e93ef7df839a0 · dfinity/icp-cli · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
name: Documentation

on:
  push:
    tags:
      - 'v*'
    branches:
      - main
      - 'docs/v*'
    paths:
      - 'docs/**'
      - 'docs-site/**'
      - 'scripts/prepare-docs.sh'
      - '.github/workflows/docs.yml'
  pull_request:
    paths:
      - 'docs/**'
      - 'docs-site/**'
      - 'scripts/prepare-docs.sh'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: write

env:
  # Site configuration - customize these for forks
  # Production (dfinity/icp-cli):
  PUBLIC_SITE: https://dfinity.github.io
  PUBLIC_BASE_PREFIX: /icp-cli
  # Forks should update these values:
  #   PUBLIC_SITE: https://your-username.github.io
  #   PUBLIC_BASE_PREFIX: /your-repo-name

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Build job - validates that docs build successfully
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Validate required environment variables
        run: |
          if [[ -z "${{ env.PUBLIC_SITE }}" ]]; then
            echo "❌ Error: PUBLIC_SITE environment variable is not set"
            exit 1
          fi
          if [[ -z "${{ env.PUBLIC_BASE_PREFIX }}" ]]; then
            echo "❌ Error: PUBLIC_BASE_PREFIX environment variable is not set"
            exit 1
          fi
          echo "✅ Required environment variables are set:"
          echo "  PUBLIC_SITE=${{ env.PUBLIC_SITE }}"
          echo "  PUBLIC_BASE_PREFIX=${{ env.PUBLIC_BASE_PREFIX }}"

      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

      - name: Setup Node
        uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: docs-site/package-lock.json

      - name: Install dependencies
        working-directory: ./docs-site
        run: npm ci

      - name: Build documentation site
        working-directory: ./docs-site
        run: npm run build
        env:
          NODE_ENV: production
          PUBLIC_SITE: ${{ env.PUBLIC_SITE }}
          PUBLIC_BASE_PREFIX: ${{ env.PUBLIC_BASE_PREFIX }}

  # Publish root index and versions list - only runs on main branch
  publish-root-files:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

      - name: Setup Node
        uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
        with:
          node-version: '20'

      - name: Prepare root files
        run: |
          mkdir -p root

          # Copy versions.json from repo
          cp docs-site/versions.json root/versions.json

          # Extract the latest version from versions.json
          LATEST_VERSION=$(jq -r ".versions[] | select(.latest == true) | .version" docs-site/versions.json)

          # If no releases yet, redirect to main branch docs
          if [[ -z "$LATEST_VERSION" ]]; then
            echo "⚠️  No releases yet, redirecting to main branch docs"
            LATEST_VERSION="main"
          else
            echo "✅ Redirecting to version: ${LATEST_VERSION}"
          fi

          # Generate index.html that redirects to latest version
          cat > root/index.html << EOF
          <!doctype html>
          <html>
            <head>
              <meta http-equiv="refresh" content="0; url=./${LATEST_VERSION}/" />
              <meta name="robots" content="noindex" />
            </head>
          </html>
          EOF

      - name: Deploy root files to GitHub Pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./root
          keep_files: true

  # Publish main branch docs for preview (always available at /main/)
  publish-main-docs:
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

      - name: Setup Node
        uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: docs-site/package-lock.json

      - name: Install dependencies
        working-directory: ./docs-site
        run: npm ci

      - name: Build main branch docs
        working-directory: ./docs-site
        run: |
          BASE_PREFIX="${PUBLIC_BASE_PREFIX:-/icp-cli}"
          echo "Building with base: ${BASE_PREFIX}/main/"
          npm run build
        env:
          NODE_ENV: production
          PUBLIC_BASE_PATH: ${{ env.PUBLIC_BASE_PREFIX }}/main/
          PUBLIC_SITE: ${{ env.PUBLIC_SITE }}

      - name: Deploy main docs to GitHub Pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-site/dist
          destination_dir: main
          keep_files: true

  # Publish versioned docs - runs on tags (v*) or docs branches (docs/v*)
  publish-versioned-docs:
    if: github.event_name == 'push' && (startsWith(github.ref, 'refs/tags/v') || startsWith(github.ref, 'refs/heads/docs/v'))
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

      - name: Setup Node
        uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # v4.2.0
        with:
          node-version: '20'
          cache: 'npm'
          cache-dependency-path: docs-site/package-lock.json

      - name: Install dependencies
        working-directory: ./docs-site
        run: npm ci

      - name: Extract version from tag or branch
        run: |
          # Use repo-specific base prefix from env vars (defaults to /icp-cli)
          BASE_PREFIX="${PUBLIC_BASE_PREFIX:-/icp-cli}"

          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
            # Tag: v0.1.0 -> extract major.minor -> 0.1
            VERSION=${GITHUB_REF#refs/tags/v}
            # Strip patch version (0.1.0 -> 0.1)
            VERSION=${VERSION%.*}
            echo "DOCS_VERSION=${VERSION}" >> $GITHUB_ENV
            echo "DOCS_BASE_PATH=${BASE_PREFIX}/${VERSION}/" >> $GITHUB_ENV
          elif [[ "${GITHUB_REF}" == refs/heads/docs/v* ]]; then
            # Branch: docs/v0.1 -> extract version -> 0.1
            VERSION=${GITHUB_REF#refs/heads/docs/v}
            echo "DOCS_VERSION=${VERSION}" >> $GITHUB_ENV
            echo "DOCS_BASE_PATH=${BASE_PREFIX}/${VERSION}/" >> $GITHUB_ENV
          else
            echo "❌ Docs should only be published for version tags (v*) or docs branches (docs/v*)"
            echo "Current ref: ${GITHUB_REF}"
            exit 1
          fi

          echo "Building docs for version ${VERSION} with base: ${BASE_PREFIX}/${VERSION}/"

      - name: Build documentation site
        working-directory: ./docs-site
        run: npm run build
        env:
          NODE_ENV: production
          PUBLIC_BASE_PATH: ${{ env.DOCS_BASE_PATH }}
          PUBLIC_SITE: ${{ env.PUBLIC_SITE }}

      - name: Deploy versioned docs to GitHub Pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs-site/dist
          destination_dir: ${{ env.DOCS_VERSION }}