GitLab Tutorials – Hosting Websites with GitLab Pages

Introduction

GitLab Pages allows you to publish static websites directly from a GitLab repository. Unlike other hosting platforms, GitLab Pages at UMD offers built-in access control—you can make your site public or restrict it to specific project members. All sites are hosted on pages.umd.edu with automatic HTTPS.

Why Use GitLab Pages at UMD?

If you're currently using GitHub Pages or considering options for hosting a research group or lab website, GitLab Pages at UMD offers several advantages:

• Access Control: Restrict your site to specific project members—useful for sharing draft materials, internal documentation, or course content with limited audiences.
• UMD Infrastructure: Your site and its source files remain on university-managed systems.
• Integration: If you're already using code.umd.edu for version control, your website lives alongside your code with no additional accounts needed.
• Local Support: The Engineering Digital Service team is available to help you get started and troubleshoot issues.

Getting Started

Step 1: Create or Import a Project

If you're starting fresh, create a new project at code.umd.edu. If you're migrating from GitHub Pages, you can import your existing repository directly: click New project > Import project > GitHub, then follow the prompts to connect your GitHub account and select the repository.

Step 2: Add a .gitlab-ci.yml File

GitLab Pages uses a CI/CD pipeline to build and deploy your site. The simplest approach is to use one of GitLab's predefined templates.

For a plain HTML site (no static site generator), create a file named .gitlab-ci.yml in your repository root with the following content:

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public
  only:
    - main

For static site generators like Jekyll, Hugo, or MkDocs, GitLab provides ready-made templates. When creating a new project, select Create from template and browse the Pages examples, or visit GitLab's Pages documentation for configuration examples.

Step 3: Commit and Deploy

Once your .gitlab-ci.yml file is in place, commit and push your changes. GitLab will automatically run the pipeline and deploy your site. You can monitor the build progress under Build > Pipelines in your project.

Step 4: Access Your Site

After a successful pipeline run, your site will be available at:

• User/Group sites: https://username.pages.umd.edu/ or https://groupname.pages.umd.edu/
• Project sites: https://username.pages.umd.edu/project-name/ or https://groupname.pages.umd.edu/project-name/

Configuring Access Control

You can control who can view your GitLab Pages site in your project settings:

1. Navigate to Settings > General
2. Expand the Pages section
3. Choose your visibility:
   • Everyone: Your site is public and accessible to anyone on the internet
   • Only Project Members: Only users with explicit access to your GitLab project can view the site

This flexibility is a key advantage over GitHub Pages, which only supports fully public sites. If you're hosting internal documentation, draft materials, or course content meant for a specific audience, the "Only Project Members" option lets you control exactly who can access it.

Using a Custom Domain

If you'd like your site available at a custom domain (such as yourlab.umd.edu), contact the Engineering Digital Service at eds@umd.edu. You'll need to add a DNS record pointing to the Pages server—EDS can walk you through the process. HTTPS certificates are handled automatically for all pages.umd.edu subdomains; custom domains may require additional configuration.

Migrating from GitHub Pages

If you have an existing GitHub Pages site, migration is straightforward:

1. Import your GitHub repository into code.umd.edu using the built-in GitHub import feature
2. Add or update the .gitlab-ci.yml file to use GitLab's syntax (the example above works for most simple sites)
3. Commit and push—your site will build and deploy automatically

Most Jekyll sites will work with minimal changes. If your GitHub Pages site uses GitHub-specific features or themes, you may need to adjust your configuration slightly.

Troubleshooting

If your site isn't appearing after the pipeline completes, check the following:

• Ensure your built site files are output to a folder named public (this is where GitLab Pages looks for content)
• Verify the pipeline completed successfully under Build > Pipelines
• Confirm your .gitlab-ci.yml includes the pages job with the correct artifacts path
• Check that you're accessing the correct URL based on your project's namespace

Getting Help and Support

For questions about GitLab Pages or if you encounter issues during setup, you can:

• Email the Engineering Digital Service directly at eds@umd.edu
• Submit a support ticket at portal.eds.umd.edu/gitlab-support

Conclusion

GitLab Pages at UMD provides a flexible, access-controlled way to host static websites for research groups, courses, documentation, and more. With automatic HTTPS, simple CI/CD deployment, and local support from EDS, it's a strong choice for faculty and staff looking to publish web content while keeping everything within UMD's infrastructure.

Get started today at code.umd.edu—and if you're currently using GitHub Pages, consider migrating to take advantage of UMD's access control features and local support.