# Deploy your Astro Site to GitLab Pages

> How to deploy your Astro site to the web using GitLab Pages.

You can use [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/) to host an Astro site for your [GitLab](https://about.gitlab.com/) projects, groups, or user account.

Looking for an example?

Check out [the official GitLab Pages Astro example project](https://gitlab.com/pages/astro)!

## How to deploy

[Section titled “How to deploy”](#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:

1. Set up [`site`](/en/reference/configuration-reference/#site) and [`base`](/en/reference/configuration-reference/#base) options in `astro.config.mjs`.

   astro.config.mjs

   ```diff
   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.

   Note

   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:

   ```astro
   <a href="/my-repo/about">About</a>
   ```

   See more about [configuring a `base` value](/en/reference/configuration-reference/#base)

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](/en/basics/project-structure/#public) 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

   ```diff
   import { defineConfig } from 'astro/config';


   export default defineConfig({
   +  outDir: 'public',
   +  publicDir: 'static',
   });
   ```

4. Change the build output in `.gitignore`. In our example we need to change `dist/` to `public/`:

   .gitignore

   ```diff
   # build output
   dist/
   public/
   ```

5. 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:

   .gitlab-ci.yml

   ```yaml
   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
   ```

6. Commit your changes and push them to GitLab.

7. 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.