0002: GitHub and GitLab Pages

Context#

Most decision repositories already live on GitHub or GitLab, and both offer free static hosting from a CI job. Writing the pipeline is the same twenty lines every time, and getting the sub-path right (/<repo>/ for a project site) is where people lose an afternoon.

Decision#

inkan init copies two ready pipelines into the repository: .github/workflows/decisions.yml for GitHub Actions and .gitlab-ci.yml for GitLab CI. Both run inkan check and build every pull or merge request, so broken references and invalid front matter fail the check, and publish the default branch to Pages. Both set BASE_PATH to the repository name, which is right for a project site and is one line to remove for a custom domain. Existing files are never overwritten.

How to use it#

1
npx inkan init
2
git add . && git commit -m "Add decision site" && git push

Delete the file for the platform you do not use.

GitHub Pages#

1
# Checks and builds every pull request (broken references or invalid front matter fail the job)
2
# and publishes main to GitHub Pages (Settings → Pages → Source: GitHub Actions).
3
name: Decisions site
4

5
on:
6
  push:
7
    branches: [main]
8
  pull_request:
9

10
permissions:
11
  contents: read
12
  pages: write
13
  id-token: write
14

15
jobs:
16
  build:
17
    runs-on: ubuntu-latest
18
    steps:
19
      - uses: actions/checkout@v4
20
        with:
21
          fetch-depth: 0 # full history for "Last updated"
22
      - uses: actions/setup-node@v4
23
        with:
24
          node-version: 22
25
      - run: npm install
26
      - run: npx inkan check # broken links, duplicate numbers, unknown statuses … as PR annotations
27
      - run: npm run build
28
        env:
29
          # Project sites live under /<repo>/. Remove for a custom domain.
30
          BASE_PATH: /${{ github.event.repository.name }}
31
      - uses: actions/upload-pages-artifact@v3
32
        if: github.ref == 'refs/heads/main'
33
        with:
34
          path: dist
35

36
  deploy:
37
    if: github.ref == 'refs/heads/main'
38
    needs: build
39
    runs-on: ubuntu-latest
40
    environment:
41
      name: github-pages
42
      url: ${{ steps.deployment.outputs.page_url }}
43
    steps:
44
      - id: deployment
45
        uses: actions/deploy-pages@v4

One-time setup in the repository: Settings, Pages, Source: “GitHub Actions”. The site appears at https://<owner>.github.io/<repo>/.

fetch-depth: 0 is not cosmetic: the “Last updated” dates on pages come from git log, and a shallow clone would date every page to the day of the build.

On GitHub Actions inkan check prints every problem as a workflow annotation on the file and line, so a broken supersedes reference shows up in the pull request’s “Files changed” view. The step exits 1 on errors and stops the job before the build; the build itself still validates front matter. If the hub lists sources, the check and the build fetch them, so the job needs credentials that can read those repositories. Every rule the command applies is listed in Check records in CI.

GitLab Pages#

1
# Checks and builds merge requests and publishes the default branch to GitLab Pages.
2
image: node:22
3

4
variables:
5
  GIT_DEPTH: 0 # full history for "Last updated"
6

7
build:
8
  script:
9
    - npm install
10
    - npx inkan check # broken links, duplicate numbers, unknown statuses …
11
    - npm run build
12
  rules:
13
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
14

15
pages:
16
  script:
17
    - npm install
18
    - npx inkan check
19
    # Project pages live under /<project>/. Remove BASE_PATH for a custom domain.
20
    - BASE_PATH="/$CI_PROJECT_NAME" npm run build
21
    - mv dist public
22
  artifacts:
23
    paths: [public]
24
  rules:
25
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

GitLab publishes the public folder of a job named pages, hence the mv. The site appears at https://<group>.gitlab.io/<project>/. For a group site or a custom domain, remove BASE_PATH=... from the build line. With repo.provider: 'gitlab' in the config, the edit and “New ADR” links point at GitLab’s web editor.

GitLab has no annotation format, so check prints its report to the job log; --format json gives a machine-readable report if you want to post it elsewhere.

What the pipelines do not do#

• No preview deployment per pull request. Download the dist artifact or run npm run preview locally.
• No caching of node_modules. Add cache: npm to setup-node, or a GitLab cache: block, if install time matters.
• No url for you. Set it in inkan.config.ts; the pipelines cannot know your final domain.
• No credentials or schedule for sources. A hub that pulls records from other repositories adds both by hand.

Consequences#

• A new repository is published with init, one commit and one click in the Pages settings.
• The default assumes a project site under /<repo>/. Custom domains need one line removed, and forgetting it produces a site whose links all start with the repository name.
• init never overwrites files, so an existing .gitlab-ci.yml or workflow keeps its content; copy the relevant jobs by hand.
• The two files encode today’s recommended actions (upload-pages-artifact@v3, deploy-pages@v4). They are yours after init and do not update with the package.