How to create a static website using GitLab Pages

Much like GitHub, Gitlab offers a web-based solution for managing coding projects, making it easier to track and resolve bugs and other issues with the project, provide information and wikis on the project's function and use, and a host of other benefits.

As you might have guessed, the idea behind GitLab Pages is, like the name, very similar to Github Pages, which provides a space for a more complex static homepage for projects, and which have been supported as a deployment option in Publii since the early beta releases. With Gitlab's increase in popularity after GitHub's acquisition by Microsoft in June 2018, we decided to implement Gitlab Pages support in Publii to allow users previously based on GitHub to move their project website across without issue.

For other Git hosts, such as Bitbucket, use the generic Git repository deployment method.

Creating a static website with GitLab Pages isn't difficult; we'll just need to complete a few simple preparatory steps on Gitlab before we can set-up the upload in Publii.

Generating an access token

You'll need an access token to let Publii upload and update your website files whenever you click the Sync button in the Publii app. Publii 0.48.2 and later support fine-grained personal access tokens. You can also use a legacy personal access token with the api scope if your GitLab instance or group allows it.

If you haven't created a GitLab project yet, follow the project setup steps below first, then return here to create a token for that project.

Fine-grained personal access token

To create a fine-grained token with the permissions Publii needs:

1. Open your avatar menu, select Edit profile, then go to Access > Personal access tokens.
2. From the Generate token dropdown, choose Fine-grained token. Enter a name, description and expiry date.
3. Under Group and project access, select the project that will store your website, or its parent group.
4. Under Add resource permissions, open the Group and project tab and add the following permissions:

Click Generate token, then copy and save the token. GitLab only displays it once.

In Publii's Repository field, enter the full project path, such as username/project or group/subgroup/project. Entering only the project name triggers a search that requires an additional Project: Read permission under the User tab. Use the full path to keep access limited to the selected project or group.

The token owner must also have permission to push to the selected branch. For a protected branch such as main, check its Allowed to push rules. Adding Protected Branch permissions to the token does not grant permission to push.

Code: Read and Code: Push are not required for Publii's GitLab Pages connection, which uses the REST API rather than the Git protocol.

Legacy personal access token

To use a legacy token with the api scope, follow these steps. The screenshots show an earlier GitLab interface, so some labels and menu positions may differ:

1. Log-in to your account on the Gitlab website:

   

2. After logging-in, open your avatar menu and click on the Edit profile option:

   

3. In the sidebar, open Access > Personal access tokens, then choose Legacy token from the Generate token dropdown:

   

4. Enter a name and expiry date for your access token, then under the Scopes heading, add a checkmark to the api setting. Finally, click the Generate token button:

   

5. Your access token will appear on the next screen - click the clipboard icon to copy it to your clipboard and save it somewhere safe to use later (once you leave this screen you will not be able to access the token again, so make sure it's been saved before moving on to the next section!):

   

Creating our static website on Gitlab Pages

Your website files need a GitLab project to be stored in. Follow these steps to create one. If you already have a project, skip to the step for adding .gitlab-ci.yml.

1. On the Gitlab site, click on the plus button in the toolbar and select New project/repository:

   

2. On the next screen, click on the Create blank project box.

   

3. Now, on the Create blank project page, give your project a name and choose its visibility level. A private repository can also host a public Pages website; access to the website is controlled separately in the project's Pages access settings. Next, click on the Create project button:

   

4. The project is now created and you'll be on the project's home screen. As Gitlab uses pipelines to publish static websites we'll have to create a special file to take care of this. First, click on the plus button, then from the dropdown menu select New file button:

   

5. On the next screen, for the Filename, type .gitlab-ci.yml and in the main code window, paste the following code:

   image: alpine:latest
   
   pages:
     stage: deploy
     script:
       - echo 'Nothing to do...'
     artifacts:
       paths:
         - public/
     only:
       - main

   The indents in the YML format are important so please make sure that you copied the file content exactly.

   

6. Once the code has been entered, hit the Commit changes button to save the file.

The first pipeline may fail because the public directory does not exist yet. Publii will upload it during the first sync.

Now you're ready to sync Publii with your GitLab Pages project! If you created the project before generating an access token, return to the token setup steps first.

Syncing your Publii static site with Gitlab

Setting-up Publii to upload to your Gitlab Pages repository is the easiest part of this tutorial, and you'll only need to do it once; after the initial setup you can simply click the Sync button to upload changes automatically in the future. Follow these steps:

1. Create a new website (or, if you already have created the website you want to use with Gitlab in Publii, open that instead) and click on the Server section in the sidebar menu to open the server settings page:

   

   
   
   
2. Enter your GitLab Pages website address in the Website URL field and select HTTPS. Check the address under Deploy > Pages in your GitLab project. New projects use a unique Pages domain by default, so the address may differ from username.gitlab.io/project-name. Enter the domain and any path without the https:// prefix, as the protocol is selected separately.
3. The Server field can be left as the default, except when you are using your own instance of GitLab (on your own servers) rather than the Gitlab site.
4. Enter the full project path in the Repository field, for example username/project or group/subgroup/project. Include any subgroups and leave out the GitLab server address. This is required when using a fine-grained token limited to the selected project or group.
5. The Branch field should contain the name of an existing branch that will be used to publish your website. Use main for the configuration above, and make sure the token owner has permission to push to it.
6. In the Token field, enter the access token value that was saved in the first part of this guide.

With this done, click Save settings, then Test connection to check access to the project and branch. Click Sync your website in the left sidebar to upload your website content to the GitLab repository.

Once the sync is complete you will see the following file structure in your repository:

• public is a directory which contains all the website files.
• .gitlab-ci.yml is the configuration file for the pipelines we created earlier.
• publii-files.json is a file used during sync; please do not modify the files in the public directory manually as this will lead to desynchronisation of the data stored under the publii-files.json file.

It can take a few minutes for GitLab to publish the uploaded files. Check the deployment status under Build > Pipelines in your project. The screenshots below show an earlier GitLab interface:

Here you can see if your pipeline works correctly.

You may also check the deployment status under Build > Jobs:

Clicking on the job ID will let you check the process output:

Once the Pages deployment completes successfully, your website will be available at the address shown under Deploy > Pages.

Useful Tips and Tricks

Looking to get a bit more control over your site? Here's some useful tricks that will help you get your site exactly how you want:

Simplify your website URL to yourusername.gitlab.io

To publish at yourusername.gitlab.io, create a project with that exact name in your personal namespace. For example, if your username is testname, name the project testname.gitlab.io.

Under Deploy > Pages, turn off Use unique domain if it is enabled and save the change. The website can then use testname.gitlab.io without a project path. Update the Website URL in Publii to match, then sync again.

Use a custom domain

If you'd prefer to use your own domain name rather than the default gitlab.io subdomain you can use this tutorial to setup a custom domain for your static website.

Is SSL available for your custom domain?

All gitlab.io subdomains have SSL enabled by default. Custom domains can also use HTTPS. We strongly recommend that you use HTTPS for your domain as the Chrome browser (since version 68) marks HTTP-only websites as not secure (more details).

Use different branches in your repo

In our tutorial we specifically use the main branch of our repo, but you are free to use other branches; you could create a documentation website for your existing repository by using a docs branch, for example. Create the branch first, add .gitlab-ci.yml to it, and replace main under only with your branch name. Use the same branch in Publii's Branch field.

Download Publii