Skip to content

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.

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

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

  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/:

    astro.config.mjs
    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
    # 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
    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.

More Deployment Guides

Contribute

What’s on your mind?

Create GitHub Issue

Quickest way to alert our team of a problem.

Community
京ICP备15031610号-99