Deploy your Astro Site to GitLab Pages

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

How to deploy

You can deploy an Astro site to GitLab Pages by using GitLab CI/CD to automatically build and deploy your site. To do this, your source code must be hosted on GitLab and you need to make the following changes to your Astro project:

Set up site and base options in astro.config.mjs.
astro.config.mjs
```
import { defineConfig } from 'astro/config';

export default defineConfig({
  site: 'https://<username>.gitlab.io',
  base: '/<my-repo>',
  outDir: 'public',
  publicDir: 'static',
});
```
site

The value for site must be one of the following:
- The following URL based on your username: https://<username>.gitlab.io
- The following URL based on your group name: https://<groupname>.gitlab.io
- Your custom domain if you have it configured in your Gitlab project’s settings: https://example.com
For GitLab self-managed instances, replace gitlab.io with your instance’s Pages domain.

base

A value for base may be required so that Astro will treat your repository name (e.g. /my-repo) as the root of your website.

Don’t set a base parameter if your page is served from the root folder.

The value for base should be your repository’s name starting with a forward slash, for example /my-blog. This is so that Astro understands your website’s root is /my-repo, rather than the default /.
Caution
When this value is configured, all of your internal page links must be prefixed with your base value:
<a href="/my-repo/about">About</a>
See more about configuring a base value
Rename the public/ directory to static/.
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/:
astro.config.mjs
```
import { defineConfig } from 'astro/config';

export default defineConfig({
  outDir: 'public',
  publicDir: 'static',
});
```
Change the build output in .gitignore. In our example we need to change dist/ to public/:
.gitignore
```
# build output
dist/
public/
```

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

Commit your changes and push them to GitLab.
On Gitlab, go to your repository’s Deploy menu and select Pages. Here you will see the full URL of your GitLab Pages website. To make sure you are using the URL format https://username.gitlab.io/my-repo, uncheck the Use unique domain setting on this page.

Your site should now be published! When you push changes to your Astro project’s repository, the GitLab CI/CD pipeline will automatically deploy them for you.