Deployment (GitHub)

publishing a wiki on GitHub

A project on GitHub publishes its wiki with one workflow that checks the wiki, builds it with wiki publish and hands the result to GitHub Pages.^[1] If the check fails, the job stops and nothing is published.^[2] What wiki publish makes is described on wiki publish, and the same guide for Cloudflare on Deployment (Cloudflare).

Workflow

Every push to main, or a run started by hand, checks the wiki, publishes it only when the check passes, and deploys what was published.^[3]

flowchart LR
  accTitle: Publishing the wiki to GitHub Pages
  accDescr: A push to main, or a run started by hand, checks the wiki. A problem fails the job and nothing is published; otherwise the site is published, uploaded and deployed to GitHub Pages.
  started(["Push to main, or run by hand"]) --> check["Check the wiki"] --> passed{"Check passed?"}
  passed -- "No" --> failed(["Job failed, nothing published"])
  passed -- "Yes" --> publish["Publish the site"] --> cname["Write the CNAME file"]
  cname --> upload["Upload the site"] --> deploy["Deploy to GitHub Pages"] --> live(["Site published"])

The action installs wiki and leaves it installed, so a later step in the same job can run it.^[4]

# .github/workflows/pages.yml
name: pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: timothymarois/wiki-builder@TAG
      - run: wiki publish _site
      - uses: actions/upload-pages-artifact@v3
        with:
          path: _site
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: github-pages
    steps:
      - uses: actions/deploy-pages@v4

Settings

GitHub Pages is switched on before the workflow first runs: in the repository's settings, under Pages and then Build and deployment, the source is GitHub Actions.^[5] Until it is, the build job passes and the deploy job fails with a 404 saying to enable GitHub Pages.^[6]

A CNAME file in the published folder does nothing, because GitHub ignores it for a site deployed by a custom workflow.^[7] GitHub Pages is free for a public repository on GitHub Free, and publishing from a private repository needs a paid plan.^[10]

Example

wiki-builder's own pages workflow checks and publishes its wiki on every push to main.^[1] It serves the result at wiki-builder.marois.dev.^[?]

External links

• Using custom workflows with GitHub Pages
• Managing a custom domain for your GitHub Pages site
• Securing your GitHub Pages site with HTTPS
• GitHub Pages limits
• actions/deploy-pages