Skip to content

G
gitlab-foss

李少辉-开发者 / gitlab-foss

通知 15
Star 0
Fork 0
G
gitlab-foss

前往新版Gitcode，体验更适合开发者的 AI 搜索 >>

切换分支/标签
查找文件 普通视图历史永久链接Permalink
pages_from_scratch.md 9.5 KB
Newer Older
G
Add latest changes from gitlab-org/gitlab@master  
GitLab Bot 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 
---
last_updated: 2020-01-06
type: reference, howto
stage: Release
group: Release Management
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---

# Create a GitLab Pages website from scratch

This tutorial shows you how to create a Pages site from scratch. You will start with
a blank project and create your own CI file, which gives instruction to the
[GitLab Runner](https://docs.gitlab.com/runner/). When your CI/CD
[pipeline](../../../../ci/pipelines/index.md) runs, the Pages site is created.

This example uses the [Jekyll](https://jekyllrb.com/) Static Site Generator (SSG).
Other SSGs follow similar steps. You do not need to be familiar with Jekyll or SSGs
to complete this tutorial.

## Prerequisites

To follow along with this example, start with a blank project in GitLab.
Create three files in the root (top-level) directory.

- `.gitlab-ci.yml` A YAML file that contains the commands you want to run.
  For now, leave the file's contents blank.

- `index.html` An HTML file you can populate with whatever HTML content you'd like,
  for example:

  ```html
  <html>
  <head>
    <title>Home</title>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
  </html>
  ```

- [`Gemfile`](https://bundler.io/gemfile.html) A file that describes dependencies for Ruby programs.
  Populate it with this content:

  ```ruby
  source "https://rubygems.org"

  gem "jekyll"
  ```

## Choose a Docker image

In this example, the Runner uses a [Docker image](../../../../ci/docker/using_docker_images.md)
to run scripts and deploy the site.

This specific Ruby image is maintained on [DockerHub](https://hub.docker.com/_/ruby).

Edit your `.gitlab-ci.yml` and add this text as the first line.

```yaml
image: ruby:2.7
```

If your SSG needs [NodeJS](https://nodejs.org/) to build, you must specify an
image that contains NodeJS as part of its file system. For example, for a
[Hexo](https://gitlab.com/pages/hexo) site, you can use `image: node:12.17.0`.

## Install Jekyll

To run [Jekyll](https://jekyllrb.com/) locally, you would open your terminal and:

- Install [Bundler](https://bundler.io/) by running `gem install bundler`.
- Create `Gemfile.lock` by running `bundle install`.
- Install Jekyll by running `bundle exec jekyll build`.

In the `.gitlab-ci.yml` file, this is written as:

```yaml
script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build
```

In addition, in the `.gitlab-ci.yml` file, each `script` is organized by a `job`.
A `job` includes the scripts and settings you want to apply to that specific
task.

```yaml
job:
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build
```

For GitLab Pages, this `job` has a specific name, called `pages`.
This setting tells the Runner you want the job to deploy your website
with GitLab Pages:

```yaml
pages:
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build
```

## Specify the `public` directory for output

Jekyll needs to know where to generate its output.
GitLab Pages only considers files in a directory called `public`.

Jekyll uses destination (`-d`) to specify an output directory for the built website:

```yaml
pages:
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d public
```

## Specify the `public` directory for artifacts

Now that Jekyll has output the files to the `public` directory,
the Runner needs to know where to get them. The artifacts are stored
in the `public` directory:

```yaml
pages:
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
```

Paste this into `.gitlab-ci.yml` file, so it now looks like this:

```yaml
image: ruby:2.7

pages:
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
```

Now save and commit the `.gitlab-ci.yml` file. You can watch the pipeline run
by going to **CI / CD > Pipelines**.

When it succeeds, go to **Settings > Pages** to view the URL where your site
is now available.

If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file
with [any of the available settings](../../../../ci/yaml/README.md). You can check
your CI syntax with the [GitLab CI/CD Lint Tool](https://gitlab.com/ci/lint).

The following topics show other examples of other options you can add to your CI/CD file.

## Deploy specific branches to a Pages site

You may want to deploy to a Pages site only from specific branches.

First, add a `workflow` section to force the pipeline to run only when changes are
pushed to branches:

```yaml
image: ruby:2.7

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH'

pages:
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
```

Then configure the pipeline to run the job for the master branch only.

```yaml
image: ruby:2.7

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH'

pages:
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'
```

## Specify a stage to deploy

There are three default stages for GitLab CI/CD: build, test,
and deploy.

If you want to test your script and check the built site before deploying
to production, you can run the test exactly as it will run when you
push to `master`.

To specify a stage for your job to run in,
add a `stage` line to your CI file:

```yaml
image: ruby:2.7

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH'

pages:
  stage: deploy
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'
```

Now add another job to the CI file, telling it to
test every push to every branch **except** the `master` branch:

```yaml
image: ruby:2.7

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH'

pages:
  stage: deploy
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'

test:
  stage: test
  script:
  - gem install bundler
  - bundle install
  - bundle exec jekyll build -d test
  artifacts:
    paths:
    - test
  rules:
    - if: '$CI_COMMIT_BRANCH != "master"'
```

When the `test` job runs in the `test` stage, Jekyll
builds the site in a directory called `test`. The job affects
all branches except `master`.

When you apply stages to different jobs, every job in the same
stage builds in parallel. If your web application needs more than
one test before being deployed, you can run all your tests at the
same time.

## Remove duplicate commands

To avoid duplicating the same scripts in every job, you can add them
to a `before_script` section.

In the example, `gem install bundler` and `bundle install` were running
for both jobs, `pages` and `test`.

Move these commands to a `before_script` section:

```yaml
image: ruby:2.7

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH'

before_script:
  - gem install bundler
  - bundle install

pages:
  stage: deploy
  script:
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'

test:
  stage: test
  script:
  - bundle exec jekyll build -d test
  artifacts:
    paths:
    - test
  rules:
    - if: '$CI_COMMIT_BRANCH != "master"'
```

## Build faster with cached dependencies

To build faster, you can cache the installation files for your
project's dependencies by using the `cache` parameter.

This example caches Jekyll dependencies in a `vendor` directory
when you run `bundle install`:

```yaml
image: ruby:2.7

workflow:
  rules:
    - if: '$CI_COMMIT_BRANCH'

cache:
  paths:
  - vendor/

before_script:
  - gem install bundler
  - bundle install --path vendor

pages:
  stage: deploy
  script:
  - bundle exec jekyll build -d public
  artifacts:
    paths:
    - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "master"'

test:
  stage: test
  script:
  - bundle exec jekyll build -d test
  artifacts:
    paths:
    - test
  rules:
    - if: '$CI_COMMIT_BRANCH != "master"'
```

In this case, you need to exclude the `/vendor`
directory from the list of folders Jekyll builds. Otherwise, Jekyll
will try to build the directory contents along with the site.

In the root directory, create a file called `_config.yml`
and add this content:

```yaml
exclude:
  - vendor
```

Now GitLab CI/CD not only builds the website,
but also pushes with **continuous tests** to feature-branches,
**caches** dependencies installed with Bundler, and
**continuously deploys** every push to the `master` branch.

## Related topics

For more information, see the following blog posts.

- [Use GitLab CI/CD `environments` to deploy your
  web app to staging and production](https://about.gitlab.com/blog/2016/08/26/ci-deployment-and-environments/).
- Learn [how to run jobs sequentially,
  in parallel, or build a custom pipeline](https://about.gitlab.com/blog/2016/07/29/the-basics-of-gitlab-ci/).
- Learn [how to pull specific directories from different projects](https://about.gitlab.com/blog/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/)
  to deploy this website, <https://docs.gitlab.com>.
- Learn [how to use GitLab Pages to produce a code coverage report](https://about.gitlab.com/blog/2016/11/03/publish-code-coverage-report-with-gitlab-pages/).