by Laurie Sheppard, USFWS

Adding a custom 404 page to a Gitlab Pages deployment

Apr 13, 2025
gitlab ci

To add a custom 404 page to a Gitlab Pages deployment, create an HTML page called 404.html and add it to the public directory of your site.

It’s not complicated, but I found the documentation hard to come by, so I’m writing it down here.

That is all.

If you want more article fluff, here’s the 404.html in my Séance app:

<!DOCTYPE html>
<html lang="en" class="flex justify-center items-center h-full touch-manipulation">
  <head>
    <meta charset="UTF-8">
    <meta name="robots" content="noindex">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="theme-color" content="#54B4D4"/>

    <meta http-equiv="refresh" content="1; url=https://seance.alexandercalvert.me">

    <link rel="icon" href="/favicon.ico">
    <link href="/src/assets/css/main.css" rel="stylesheet">

    <script>window.location.href = "https://seance.alexandercalvert.me"</script>

    <title>404</title>
  </head>
  <body>
    <h1>404</h1>
    <h2>This page doesn't exist</h2>
    <span>You are being redirected to the landing page. If you are not redirected automatically, <a href="https://seance.alexandercalvert.me">follow the link.</a></span>
  </body>
</html>