Setting up Pelican to Automatically Deploy to GitLab Pages

Posted on Tue 27 August 2019 in Technology • 3 min read

I posted last year about my switch from WordPress to a statically generated site generated by Pelican by GitHub Pages in a blog post. Since then, my hosting situation has changed a couple of times. I first migrated to deploy straight to a DigitalOcean Droplet from Travis CI. Then, I migrated to GitLab and used GitLab CI/CD to do the same thing. Now that GitLab Pages has support for automatically handling the Let’s Encrypt SSL Certificate on custom domains, I’ve moved to GitLab Pages for hosting as well.

In summary, I am hosting my site publicly on GitLab Pages here: https://gitlab.com/sumner/sumnerevans.com. Unlike my previous setup, the master branch is the branch from which everything is deployed. When a new commit is added to master, I use GitLab CI/CD to deploy to GitLab Pages automatically. Currently, it takes about 2-3 minutes for it to deploy after I commit a change.

In this article, I’m going to walk you through how to set up the deployment pipeline to get your site deploying on GitLab Pages.

Prerequisites

For this article, I assume that you…

  • Already have basic competency in Git and GitLab (although I don’t assume knowledge of GitLab CI/CD).
  • I assume that you already have a Pelican site setup. If you don’t, the Pelican Documentation is really good. The pelican-quickstart command works great, and will help you easily get started with your site.

Setting up Pelican

First, we need to make sure that Pelican is configured to output to the correct directory so that GitLab Pages can find the site files.

  1. Make sure that all of your Pelican source code is committed to a branch in your repository.

  2. Make sure that Pelican is set up with a Makefile which publishes the site to <repo_root>/public. The pelican-quickstart script can automatically generate this for you. If not you can look at the one for this site and adapt to your needs here.

    If using the pelican-quickstart Makefile, ensure sure that the OUTPUTDIR is set to $(BASEDIR)/public as that is required for GitLab Pages to recognize your site’s files.

  3. If you have not already created a requirements.txt file, do so now in the root of your repository. It needs at least the following content:

    pelican
    Markdown
    beautifulsoup4
    

    Add any other dependencies of your site to this file. (My site depends on typogrify as well, so that is also in the requirements.txt file.)

Set up GitLab CI/CD

Now we need to configure GitLab CI/CD to automatically build the site. To do that, add a .gitlab-ci.yml file with the following contents:

# Build and deploy the pelican site.
pages:
  image: python:3.6-alpine
  stage: deploy
  only:
    - master
  before_script:
    - apk update && apk upgrade && apk add git make
    - pip install --upgrade pip
    - pip install -r requirements.txt
  script:
    - make publish
  artifacts:
    paths:
      - public

Note

The above file is assuming that you are using a pelican-quickstart Makefile, and that you only want to deploy the master branch. Modify as necessary if you are using a different Makefile or branch.

Also, if you have any other dependencies or custom build steps, add them to before_script or script.

Now, commit and push that file to GitLab, and let the magic occur. You can view the status of your build by going to the “CI / CD” tab of your repo. You can also access the settings for GitLab Pages in “Settings -> Pages”. There you can add a new domain to allow it to use a custom domain (as I do), and otherwise manage your site.

Conclusion

That’s it! Your site should not be available at the URL that the “Settings -> Pages” has listed. Whenever you commit new changes to master, it will automatically rebuild the site, and deploy it to GitLab Pages. Go ahead; try it out for yourself!