gitlab.mdx

title	description	type	i18nReady
Deploy your Astro Site to GitLab Pages	How to deploy your Astro site to the web using GitLab Pages.	deploy	true

import { Steps } from '@astrojs/starlight/components';

You can use GitLab Pages to host an Astro site for your GitLab projects, groups, or user account.

:::tip[Looking for an example?] Check out the official GitLab Pages Astro example project! :::

How to deploy

1. Set the correct `site` in `astro.config.mjs`.

2. Rename the public/ directory to static.

3. Set outDir:public in astro.config.mjs. This setting instructs Astro to put the static build output in a folder called public, which is the folder required by GitLab Pages for exposed files.

   If you were using the public/ directory as a source of static files in your Astro project, rename it and use that new folder name in astro.config.mjs for the value of publicDir.

   For example, here are the correct astro.config.mjs settings when the public/ directory is renamed to static/:

   import { defineConfig } from 'astro/config';
   
   export default defineConfig({
     site: 'https://<user>.gitlab.io',
     base: '/<project-name>',
     outDir: 'public',
     publicDir: 'static',
   });

4. Create a file called .gitlab-ci.yml in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:

   pages:
     # The Docker image that will be used to build your app
     image: node:lts
   
     before_script:
       - npm ci
   
     script:
       # Specify the steps involved to build your app here
       - npm run build
   
     artifacts:
       paths:
         # The folder that contains the built files to be published.
         # This must be called "public".
         - public
   
     only:
       # Trigger a new build and deploy only when there is a push to the
       # branch(es) below
       - main