docs/content/deploy/gitlab-ci.md (1742B)
1 +++
2 title = "GitLab Pages"
3 description = "One .gitlab-ci.yml, and the subpath that trips people up"
4 weight = 50
5 toc = true
6 +++
7
8 ```yaml
9 # .gitlab-ci.yml
10 pages:
11 image: alpine:latest
12 script:
13 - wget -qO- https://github.com/debuman/sqzass/releases/latest/download/sqzass-x86_64-unknown-linux-musl.tar.gz | tar xz --strip-components=1
14 - ./sqzass build
15 artifacts:
16 paths: [public]
17 rules:
18 - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
19 ```
20
21 `alpine` works because the release is statically linked — there is no glibc in
22 that image and nothing here needs one. The job is named `pages` and the artifact
23 directory is `public` because GitLab looks for exactly those two names.
24
25 ## The subpath
26
27 Unless you have set a custom domain, a GitLab project site is served at
28 `https://<group>.gitlab.io/<project>/`. That path has to be in `base_url`:
29
30 ```toml
31 base_url = "https://mygroup.gitlab.io/myproject"
32 ```
33
34 sqzass then puts `/myproject` in front of every URL it generates — links,
35 stylesheet hrefs, the search index location, everything — while the output
36 directory stays flat, because that directory *is* the root GitLab serves.
37
38 Getting this wrong is quiet rather than loud. The site builds, the pages exist,
39 and every link and stylesheet resolves one level too high, so you get 404s and
40 an unstyled page from a build that reported success.
41
42 For a user or group site (`<group>.gitlab.io`) there is no path, and `base_url`
43 is just the domain.
44
45 ## Merge request previews
46
47 ```yaml
48 pages:
49 # …
50 script:
51 - wget -qO- … | tar xz --strip-components=1
52 - ./sqzass build --base-url "$CI_PAGES_URL"
53 ```
54
55 `$CI_PAGES_URL` already contains the project path, so this is also the shortest
56 way to avoid writing the subpath twice.