using-gitlab-deploy-project-pages.md 4.4 KB
Newer Older
Philipp Marek's avatar
Philipp Marek committed
1
title: Using GitLab to deploy project pages -- Common-Lisp.net FAQ
2
3
4
5
6
7
8
---

{table-of-contents :depth 2 :start 2 :label "Table of contents" }

# Using GitLab to deploy project pages

This page contains instructions on how to deploy your project pages
9
(those hosted on `https://<your-project>.common-lisp.dev`).
10
11
12
13
14
15
16
17

Using deployment through GitLab, you can use your preferred site
generator in your preferred setup: from "simply copy the repository
content" to builds depending on specialized Docker images, all these
are supported by our common-lisp.net setup.

## Step 1: Create a repository for your project pages

18
19
20
21
In order to deploy your project pages to `https://<project>.common-lisp.dev`,
you need a project in GitLab named `<project>.common-lisp.dev` in the group
named `<project>`. That is, the resulting repository will be viewable at the
URL `https://gitlab.common-lisp.net/<project>/<project>.common-lisp.dev`.
22
23
24
25
26
27
28
29
30
31
32
33
34
35


## Step 2: Add content to the repository

After the repository has been created, the site content can be
added. Take into account that any content that needs to be deployed
should end up in a subdirectory called `public/`.

A very simple example of deploying content straight from the repository
is the [cl-couch-site](https://gitlab.common-lisp.net/cl-couch/cl-couch-site/)
project. It holds the content to be deployed in a `src/` subdirectory
which can simply be renamed to `public/`. No further processing is
required.

36
37
38
39
More complex build steps can be found in
the [clo/cl-site](https://gitlab.common-lisp.net/clo/cl-site/) and the
[cl-tar/cl-tar.common-lisp.dev](https://gitlab.common-lisp.net/cl-tar/cl-tar.common-lisp.dev/)
projects respectively.
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57


## Step 3: Add continuous integration through `.gitlab-ci.yml`

Once a repository has been set up and seeded with content, deployment
instructions have to be added through GitLab's CI (Continuous Integration)
platform. The example below is the simplest deployment CI instruction,
deploying static site content without processing.

    pages:
      stage: deploy
      script: mv src public
      artifacts:
         paths:
           - public
      only:
        - master

58
59
60
61
62
63
64
65
66
67
68
The above defines the special purpose `pages` build job known to GitLab to be
associated with GitLab Pages deployment.

GitLab CI provides two ways to order jobs. First, jobs can be tied to various
"stages" and jobs in any given stage are executed only after the previous
stages have completed. Alternatively, jobs can specify a list of "needs" and a
job can be executed once its needs are met, regardless if previous stages have
finished. In this example, the `pages` job is added to the "deploy" stage.

The `pages` job must upload the `public` folder as an artifact. Whatever is
present in the `public` folder is served using GitLab Pages.
69
70
71

To prevent every intermediate result on every branch from being
deployed to your project site, the job is restricted to building
Erik Huelsmann's avatar
Erik Huelsmann committed
72
from the `master` branch only, using the
73
74
75
76
77
78
79
80
81
82
83
84

    only:
      - master

fragment.

Then, last but not least, the fragment `script: mv src public`
instructs the CI system to perform the "build" for this repository
(i.e. nothing more than to rename `src` to `public`).

As mentioned in the previous section, other, more complex, setups
and build instructions are possible. See for examples the [clo/
85
86
87
88
cl-site](https://gitlab.common-lisp.net/clo/cl-site/) and [cl-tar/ 
cl-tar.common-lisp.dev](https://gitlab.common-lisp.net/cl-tar/cl-tar.common-lisp.dev/) projects.
Note however, that `clo/cl-site` doesn't deploy to a `<project>.common-lisp.dev/`
page (but to `https://common-lisp.net` instead).
89
90
91
92
93
94
95
96


## Step 4: Deploy and test your new project pages

If the syntax of your `.gitlab-ci.yml` file is correct, a new build
will run on every push or merge to the master branch. With each successful
build, a new deployment will take place.

Erik Huelsmann's avatar
Erik Huelsmann committed
97
98
99
100
101
Note that if you want to check that your `.gitlab-ci.yml` file has
valid syntax, you can use GitLab's "CI Lint" application. This application
is available in every project on the "Pipelines" page. For the "clo/cl-site"
project, it's located at https://gitlab.common-lisp.net/clo/cl-site/-/ci/lint

102
103
104
105
106
Please note that if you're migrating existing project pages from
`/project/<project>/public_html` to GitLab based deployments that
your new site won't show up until the `public_html` directory has
been removed (or renamed).

Erik Huelsmann's avatar
Erik Huelsmann committed
107
108
For more information on how to use GitLab Pages and GitLab CI,
please see https://docs.gitlab.com/ce/user/project/pages/#overview .