Deploy no GitLab Pages

O GitLab Pages serve arquivos estáticos a partir de um diretório chamado public, gerado por um job de CI com nome pages. O trabalho, então, é fazer o Next.js gerar HTML estático e entregar esse HTML no lugar certo.

1. Export estático do Next.js

import { createMDX } from 'fumadocs-mdx/next';

const withMDX = createMDX();

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  // Gera `/rota/index.html` para que o host estático sirva links diretos após um refresh.
  trailingSlash: true,
};

export default withMDX(nextConfig);

• output: 'export' faz next build escrever o site pronto na pasta out/.
• trailingSlash: true gera rota/index.html em vez de rota.html. Sem isso, atualizar a página em uma URL profunda dá 404 no GitLab Pages.

2. O pipeline

stages:
  - build
  - deploy

build:
  stage: build
  image: oven/bun
  script:
    - bun install
    - bun run build
  artifacts:
    paths:
      - out

pages:
  stage: deploy
  script:
    - echo "Deploying to GitLab Pages..."
    - mv out public
  artifacts:
    paths:
      - public
    expire_in: 30 days

Como isso funciona:

1. O job build roda na imagem oven/bun, instala as dependências e gera out/.
2. artifacts: paths: [out] guarda o resultado — sem isso, o próximo estágio começaria com o diretório vazio.
3. O job precisa se chamar pages: é esse nome que o GitLab reconhece como publicação.
4. mv out public renomeia o diretório para o único nome que o Pages serve.
5. O artefato public é o que vai para o ar.

3. Publicando

git add .
git commit -m "docs: nova página"
git push

Acompanhe em Build → Pipelines e, quando terminar, a URL aparece em Deploy → Pages.

Ajustes que costumam aparecer

O site sobe sem CSS ou com links quebrados

Acontece quando o projeto é servido em um subcaminho, como https://<grupo>.gitlab.io/<projeto>/. Nesse caso o Next.js precisa saber o prefixo:

const nextConfig = {
  output: 'export',
  trailingSlash: true,
  basePath: '/fumadocs-gitlab-pages',
};

Se o projeto usa o domínio único do GitLab Pages (uma URL própria do tipo https://<projeto>-<hash>.gitlab.io/, hoje o padrão) ou um domínio personalizado, o site fica na raiz e basePath não é necessário.

Publicar só a partir da branch principal

Por padrão o pipeline roda em qualquer branch. Para publicar apenas o que entra na main:

pages:
  stage: deploy
  script:
    - mv out public
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

O build demora a cada push

Vale guardar o cache das dependências entre execuções:

build:
  stage: build
  image: oven/bun
  cache:
    key:
      files:
        - bun.lock
    paths:
      - node_modules
  script:
    - bun install
    - bun run build
  artifacts:
    paths:
      - out

Referências

• GitLab Pages — documentação oficial
• Next.js — Static Exports
• Fumadocs — Static Export