English
About this handbook

This handbook belongs to QuartzControl version 1.1.0 and explains every one of its screens; every screen links to its page here.

How to write notes so they make good pages is in the Example handbook.

Graphansicht

6.2 – GitHub Pages

3 Min. Lesezeit

GitHub Pages is the route QuartzControl accompanies furthest: creating a repository, setting up a target, configuring Pages, a custom domain, HTTPS — all from within QuartzControl.

That needs a GitHub token with the repo permission in the settings.

1. A repository

If there is none yet, Git sync creates one: a name, public or private, and it is entered as origin right away.

Private and Pages do not go together on the free plan

GitHub Pages exists for private repositories only on the paid plans. Anyone publishing via Pages needs a public repository on the free plan. That can be changed on GitHub later.

2. A target of type “Git branch”

Provider GitHub, plus the branch published to — usually gh-pages.

Not the branch you work on. A deploy replaces the target branch wholesale with the current build; QuartzControl asks about this explicitly before every deploy and refuses the current or the default branch.

3. Setting up Pages

The GitHub Pages card reads the state directly from GitHub and shows four states: Published, Building, Failed, Never built.

If Pages is not set up for the repository yet, a button creates it and points it at this branch. If origin does not point at github.com, QuartzControl says so and refers to Git sync — from here it will not work then.

4. Custom domain and HTTPS

Custom domain records the address with GitHub, not in the branch. That is the decisive difference from a CNAME file: it survives every deploy, even though a deploy replaces the branch wholesale.

Enforce HTTPS can only be switched on once GitHub has issued the certificate — which takes a few minutes after setting the domain. Try too early and QuartzControl says exactly that, suggesting you try again later.

Without a custom domain the switch is locked, and that too with a reason: an address on github.io is always served over HTTPS anyway.

Other providers on the same route

The “Git branch” target knows three providers, and QuartzControl says for each what happens afterwards:

  • GitHub — in the repository settings, Pages must point at this branch.
  • Codeberg — serves the pages branch directly; after the first push the site is reachable with no further settings.
  • GitLab — the branch alone publishes nothing there. A CI job has to deliver the files as a public artifact. The push works all the same, only nothing follows on its own.