TechPrufer
Get started
GitLab
GitLab logoGitLab · Feature trail

Static Website Hosting with GitLab Pages

24 posts · Apr 2016 – Mar 2025

What this trail covers

GitLab Pages has evolved its architecture to use API-based configuration, reducing daemon startup time from minutes to seconds. This change sources domain configuration via an internal API endpoint, caching it in memory. Future plans include transitioning from NFS to object storage and enabling Kubernetes deployment. For self-managed instances, API-based configuration can now be enabled via documentation guides. This post details how a user leveraged GitLab Pages and CI/CD to automate the deploy of review apps and versioned documentation using parallel deployments and dynamic path prefixes.

All GitLab trails
  1. Build a new website in a few easy steps with GitLab PagesThis post provides a step-by-step guide for users to create and host a personal website using GitLab Pages. It details project creation, adding HTML and CSS files, configuring the `.gitlab-ci.yml` file for deployment, and accessing the live website. It also offers customization tips for the website's content and images.
  2. GitLab Pages features review apps and multiple website deploymentIntroduced Parallel Deployments for GitLab Pages, allowing multiple versions of a static website to be deployed simultaneously. This is achieved by dynamically generating `path_prefix` values in `.gitlab-ci.yml` for merge request review apps (using `CI_MERGE_REQUEST_IID`) and for versioned documentation (using `CI_COMMIT_BRANCH`). The `pages.path_prefix` property is now configurable, and the `environment.url` property can be used to link review apps directly to merge requests.
  3. How to host VueJS apps using GitLab PagesThis post provides a tutorial on hosting VueJS applications using GitLab Pages and CI/CD. It details setting up a VueJS application with vue-cli, configuring the `.gitlab-ci.yml` file for deployment to GitLab Pages, and adjusting the `vue.config.js` file to set the output directory to 'public' and correctly configure the public path. It demonstrates a practical application of GitLab Pages for static website hosting.
  4. Use GitLab and MITRE ATT&CK Navigator to visualize adversary techniquesThis post details how to fork an example GitLab project to deploy the MITRE ATT&CK Navigator web application using GitLab Pages and CI/CD. It explains how to customize the application by modifying YAML files in the `layers/` directory, which are then processed by a Python script to generate JSON layers for the Navigator. The CI/CD pipeline automates the download of the Navigator application, injection of custom layers, and building of the static website for deployment via GitLab Pages. It also highlights features of the ATT&CK Navigator app for visualizing technique coverage.
  5. How to deploy a React application to Amazon S3 using GitLab CI/CDThis post details the technical steps for deploying a React application to Amazon S3 using GitLab CI/CD. It covers configuring an S3 bucket for static website hosting, setting up public read permissions, manually building and uploading the React app, and configuring AWS IAM OIDC for secure credential retrieval from GitLab CI. The CI/CD pipeline uses temporary AWS credentials obtained via OIDC to upload the built application to S3.
  7. Monitor your web attack surface with GitLab CI/CD and GitLab PagesThis post details the implementation of a web application attack surface monitoring solution using GitLab CI/CD and GitLab Pages. It outlines the creation of three shell scripts (`setup.sh`, `discover-services.sh`, `take-screenshots.sh`) to install tooling (httpx, gowitness), discover web services, and generate a static screenshot report. The `.gitlab-ci.yml` file is configured to orchestrate these scripts, with artifacts generated for job outputs and the `public` directory deployed via GitLab Pages. The post also covers setting up CI variables for targets and scheduling pipeline runs.
  8. How to publish your Astro Site with GitLab PagesThis post provides a step-by-step guide on how to publish an Astro site using GitLab Pages. It details configuring Astro for GitLab Pages by adjusting `astro.config.mjs` to set `outDir` to 'public' and `publicDir` to 'static', and configuring the `base` and `site` properties for correct asset loading. It also outlines the process of setting up a remote repository on GitLab, creating a `.gitlab-ci.yml` file using the Pages wizard with a 'node:lts' build image, and configuring `npm ci` and `npm run build` commands for the pipeline. The post emphasizes the role of the `pages` job in GitLab CI/CD for deploying artifacts from the 'public' directory.
  9. How to choose the right static site generatorThis post provides a guide on choosing a static site generator (SSG) by outlining an evaluation toolkit (use case, languages/frameworks, ecosystem, community, specialty). It then reviews several SSGs (Hugo, Zola, Jekyll, Hexo, GatsbyJS, Astro) and discusses their benefits, features, and deployment options, with a specific focus on deploying to GitLab Pages. It highlights the single binary approach of Hugo and Zola, and the standard approach of Jekyll and Hexo, and touches on more flexible SSGs like GatsbyJS and Astro.
  10. Publishing Obsidian.md notes with GitLab PagesThis post details how to use GitLab Pages and CI/CD pipelines with MkDocs to publish Obsidian.md notes as a static website. It covers setting up the file structure, configuring MkDocs, and setting up the `.gitlab-ci.yml` file for deployment.
  11. How to Read Open Source: Finding Middleman CallbacksThis post details how to find and utilize Middleman lifecycle callbacks by reading the open-source codebase. It provides a list of core Middleman callbacks and a step-by-step guide on how to locate them within the Middleman repository. The author also plans to contribute this information back to the Middleman documentation.
  12. Using GitLab Pages to Report Local COVID-19 RatesThis post details how a user leveraged GitLab Pages and CI/CD pipelines to automate the download, calculation, and publishing of local COVID-19 infection rates to a static website. It demonstrates the use of Kotlin scripts, Gradle, GitLab CI/CD jobs for build and deploy stages, and d3.js for data visualization, all scheduled via GitLab Pipeline Schedules.
  13. How GitLab Pages uses the GitLab API to serve contentThis post details the transition of GitLab Pages from a file-based configuration (config.json) to an API-based configuration for domain setup. This change significantly reduces daemon startup time from approximately 25 minutes to a few seconds by querying an internal API endpoint on demand and caching the configuration. It also outlines the ongoing work to remove the NFS dependency by transitioning to object storage, which will enable Kubernetes deployment in the future. For self-managed instances, a workaround is provided to enable API-based configuration, with official documentation to follow.
  14. Publishing Accessibility Reports in GitLab PagesThis post details how to integrate automated accessibility testing into a GitLab CI/CD pipeline and publish the resulting HTML reports to GitLab Pages. It outlines the steps to include the `Verify/Accessibility.gitlab-ci.yml` template, configure the `a11y_urls` variable, and ensure the generated report is placed in the `public` directory and renamed to `index.html` for proper rendering on GitLab Pages. The post also references a previous blog post on publishing code coverage reports to GitLab Pages as inspiration.
  15. How GitLab Pages made our Sketch design handoffs easier and fasterThis post details a workflow for design handoffs using Sketch Measure to generate design specs, committing them to a GitLab Design project, and using GitLab CI/CD to publish these specs via GitLab Pages. It highlights the benefits of this automated process for efficiency, cost savings, and collaboration between designers and developers. It also introduces the use of Git hooks for commit message transparency and job artifacts for viewing previous versions of specs.
  16. New: How to get up and running quickly using GitLab Pages templatesIntroduces a new feature in GitLab 11.8 that allows users to select popular GitLab Pages templates directly from the new project setup screen, simplifying the creation of new static websites. Details the process of creating a new project from a Hugo template, editing the `config.toml` file to set the correct `baseurl`, and triggering the CI/CD pipeline for deployment. Also includes a personal anecdote about contributing to the feature and encourages others to contribute to open source.
  17. Update about GitLab PagesThis post details a critical infrastructure change for GitLab Pages users with custom domains. Following a migration of GitLab.com to GCP, a legacy Azure load balancer serving GitLab Pages was inadvertently cleaned up. This resulted in users with A records pointing to the old Azure IP address losing access to their GitLab Pages sites. The post provides the old and new IP addresses and instructs affected users to update their DNS records to the new GCP IP address to restore service.
  18. Creating open course environments with GitLab and Grav CMSThis post details how an educator leveraged GitLab and Grav CMS to create an open course environment, demonstrating a practical application of GitLab for content management and collaboration. It highlights the use of GitLab for version control of course materials, collaborative editing by students, and integration with a flat-file CMS (Grav) that uses Markdown. The author also discusses the benefits of open-source software in education and provides a specific example with the CMPT-363 course hub, releasing an open-source version of the project.
  19. Building a new GitLab Docs site with Nanoc, GitLab CI, and GitLab PagesThis post details the rebuilding of the GitLab Docs site using Nanoc, GitLab CI, and GitLab Pages. It describes the build process, including cloning documentation from multiple repositories (CE, EE, Omnibus, Runner) into a single Nanoc project, using Rake tasks for repository management, and leveraging Nanoc's rules for Markdown processing (Redcarpet, Rouge for syntax highlighting) and asset handling. It also outlines the CI/CD pipeline for testing (link validation, SCSS linting), building, and deploying the static site to GitLab Pages.
  20. Publish code coverage report with GitLab PagesThis post details how to configure SimpleCov for Ruby RSpec tests, generate HTML code coverage reports, and publish them using GitLab CI/CD and GitLab Pages. It outlines the `.gitlab-ci.yml` configuration for running tests, storing artifacts, and deploying the reports to GitLab Pages. It also covers how to handle parallel test execution by merging partial coverage reports and how to add a code coverage badge to the README.md file.
  21. GitPitch Slideshow Presentations for Developers on GitLabThis post introduces GitPitch, a service that allows developers to create slideshow presentations directly from Markdown files within GitLab repositories. It details how to create a PITCHME.md file, the convention for defining slides using #HSLIDE, and how GitPitch generates a public URL for the presentation. It also covers customization options like themes and background images, and how GitPitch integrates with the GitLab workflow for versioning and audience tailoring. The post highlights the benefits of using GitPitch for developers to present their code and ideas efficiently.
  22. Posting to your GitLab Pages blog from iOSThis post details a workflow for posting to a GitLab Pages blog from an iOS device using a Static Site Generator (SSG). It outlines the use of Git operations apps (Working Copy) and text editors (Editorial) on iOS to clone a repository, create new branches, write content, add images, commit changes, and push them to GitLab. The process leverages GitLab CI/CD to automatically build and deploy the website upon merging changes to the main branch. It also discusses the limitations of this mobile workflow, such as the inability to preview the site locally.
  23. SSGs Part 3: Build any SSG site with GitLab PagesThis post details how to use GitLab Pages and GitLab CI to build and host any Static Site Generator (SSG) site. It provides examples of SSGs across Ruby, Node.js, Python, and Go environments, along with their corresponding `.gitlab-ci.yml` configurations. The core requirement for GitLab CI is a `pages` job that generates the compiled site into a `public` folder. It also links to previous posts in the series and provides resources for further help.
  24. SSGs Part 2: What are modern static site generatorsThis post provides an overview of modern Static Site Generators (SSGs), explaining their benefits (speed, cost savings, reduced loading times, crash resilience), structure (environment, template engine, markup language, preprocessors, directory structure), built-in features (local preview servers, LiveReload, preprocessor compilers), blog-aware capabilities, supported content (client-side processing, common file types, interactive services, utilities), and limitations (user registration, admin access, server-side processing). It specifically mentions GitLab Pages as a platform for building SSG sites.
  25. SSGs Part 1: A Static vs Dynamic WebsiteThis post introduces the fundamental differences between static and dynamic websites, explaining their respective advantages and disadvantages. It details how static websites are composed of HTML, CSS, and JavaScript files served directly by a web server, while dynamic websites involve server-side processing and database interaction. The post also touches on the history of the web, the evolution of server processing, and the benefits of Static Site Generators (SSGs) for creating static websites, particularly in conjunction with GitLab Pages.
  26. Hosting on GitLab.com with GitLab PagesThis post details the initial setup and usage of GitLab Pages for hosting static websites. It covers creating a new project, configuring `.gitlab-ci.yml` for plain HTML, Jekyll, and Hexo websites, and uploading website content. It also briefly mentions custom domain setup and the availability of GitLab Pages for GitLab.com and EE/CE users.
  27. Get Started with GitLab PagesThis post announces the availability of GitLab Pages in EE 8.3 and custom domains/TLS in EE 8.5, making it free on GitLab.com. It provides links to new resources like a quickstart guide and documentation, and showcases example projects for various static site generators (Jekyll, Pelican, Hugo, Middleman, Hexo, Brunch, Metalsmith, Harp) all powered by GitLab CI. It also announces a live webcast on GitLab CI.