Sruthi Chandran a572b6d2b1 New upstream version 11.5.6+dfsg

2019-01-03 12:48:30 +05:30

10 KiB

Raw Blame History

description
Learn how to use GitLab Pages to deploy a static website at no additional cost.

GitLab Pages

GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab.

You can use it either for personal or business websites, such as portfolios, documentation, manifestos, and business presentations, and attribute any license to your content.


Use any static website generator or plain HTML		Create websites for your projects, groups, or user account		Host on GitLab.com for free, or on your own GitLab instance		Connect your custom domain(s) and TLS certificates

Pages is available for free for all GitLab.com users as well as for self-managed instances (GitLab Core, Starter, Premium, and Ultimate).

Overview

To publish a website with Pages, you can use any Static Site Generator (SSG), such as Jekyll, Hugo, Middleman, Harp, Hexo, and Brunch, just to name a few. You can also publish any website written directly in plain HTML, CSS, and JavaScript.

Pages does not support dynamic server-side processing, for instance, as .php and .asp requires. See this article to learn more about static websites vs dynamic websites.

Availability

If you're using GitLab.com, your website will be publicly available to the internet. If you're using self-managed instances (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the Pages admin settings chosen by your sysdamin, who can opt for making them public or internal to your server.

How it works

To use GitLab Pages, first you need to create a project in GitLab to upload your website's files to. These projects can be either public, internal, or private, at your own choice. GitLab will always deploy your website from a very specific folder called public in your repository. Note that when you create a new project in GitLab, a repository becomes available automatically.

To deploy your site, GitLab will use its built-in tool called GitLab CI/CD, that will build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named .gitlab-ci.yml, which you can create and modify at will.

You can either use GitLab's default domain for GitLab Pages websites, *.gitlab.io, or your own domain (example.com). In that case, you'll need admin access to your domain's registrar (or control panel) to set it up with Pages.

Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your site under the HTTPS protocol.

Getting started

To get started with GitLab Pages, you can either create a project from scratch or quickly start from copying an existing example project, as follows:

Choose an example project to fork: by forking a project, you create a copy of the codebase you're forking from to start from a template instead of starting from scratch.
From the left sidebar, navigate to your project's CI/CD > Pipelines and click Run pipeline so that GitLab CI/CD will build and deploy your site to the server.
Once the pipeline has finished successfully, find the link to visit your website from your project's Settings > Pages.


Fork an example project		Deploy your website		Visit your website's URL

Your website is then visible on your domain, and you can modify your files as you wish. For every modification pushed to your repository, GitLab CI/CD will run a new pipeline to publish your changes to the server.

You can also take some optional further steps:

Remove the fork relationship (You don't need the relationship unless you intent to contribute back to the example project you forked from).
Make it a user/group website

Watch a video tutorial with all the steps above!

Advanced options:

Use a custom domain
Apply SSL/TLS certification to your custom domain

Explore GitLab Pages

To learn more about GitLab Pages, read the following tutorials:

Static websites and GitLab Pages domains: Understand what is a static website, and how GitLab Pages default domains work
Projects for GitLab Pages and URL structure: Forking projects and creating new ones from scratch, understanding URLs structure and baseurls
GitLab Pages custom domains and SSL/TLS Certificates: How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates
Creating and Tweaking GitLab CI/CD for GitLab Pages: Understand how to create your own .gitlab-ci.yml for your site
Technical aspects, custom 404 pages, limitations

GitLab Pages with Static Site Generators (SSGs)

To understand more about SSGs, their advantages, and how to get the most from them with Pages, read through this series:

GitLab Pages with SSL/TLS certificates

If you're using GitLab Pages default domain (.gitlab.io), your website will be automatically secure and available under HTTPS. If you're using your own domain, you can optionally secure it with with SSL/TLS certificates. You can read the following tutorials to learn how to use these third-party certificates with GitLab Pages:

CloudFlare
Let's Encrypt (mind that although this article is out-of-date, it can still be useful to guide you through the basic steps)

Advanced use

There are quite some great examples of GitLab Pages websites built for some specific reasons. These examples can teach you some advanced techniques to use and adapt to your own needs:

Admin GitLab Pages for CE and EE

Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with the admin guide.

Watch a video tutorial for getting started with GitLab Pages admin!

More information about GitLab Pages

Announcement (2016-12-24): "We're bringing GitLab Pages to CE"
Announcement (2017-03-06): "We are changing the IP of GitLab Pages on GitLab.com"

10 KiB Raw Blame History