Using GitLab Pages

1. Configuring GitLab Pages

Setting	Description	Value/Example
pages.enabled	Enables GitLab Pages for the project	`true`
pages.public	Makes the Pages site publicly accessible	`false`
pages.domain	Custom domain for the Pages site (optional)	`docs.example.com`
pages.path	Path to the static files (default: `public`)	`build`

Example: GitLab Pages Configuration in `.gitlab-ci.yml`

pages:
  stage: deploy
  script:
    - mkdir -p public
    - cp -r * public/
  artifacts:
    paths:
      - public
  only:
    - main

Note: GitLab Pages requires the public directory to be present in the artifacts for deployment.

2. Setting Pages Artifacts

Property	Description	Default	Notes
pages	Directory to publish artifacts from	`public`	Can be any directory path relative to project root
artifact	Artifact name to use in job	`public`	Used in `artifacts` section of job

Example: Configure GitLab Pages artifacts

pages:
  stage: deploy
  script:
    - mkdir -p public
    - cp -r _site/* public/
  artifacts:
    paths:
      - public
  only:
    - main

Note: The public directory must exist and contain the built static files for GitLab Pages to serve them.

3. Using Custom Domains

Property	Value	Description
pages.domain	`example.com`	Custom domain to use for GitLab Pages
pages.certificate	`cert.pem`	SSL certificate file for custom domain (optional)
pages.key	`key.pem`	SSL key file for custom domain (optional)

Example: Configuring Custom Domain in `.gitlab-ci.yml`

pages:
  stage: deploy
  script:
    - mkdir -p public
    - cp -r * public/
  artifacts:
    paths:
      - public
  only:
    - main

# Custom domain configuration
variables:
  GITLAB_PAGES_DOMAIN: example.com

Note: Ensure your DNS is properly configured to point to GitLab Pages. The domain must be verified in the GitLab project settings.

Warning: Custom domains require SSL certificates to be valid. GitLab Pages supports automatic certificate management via Let's Encrypt for verified domains.

4. Deploying Static Site Generators

Generator	Build Command	Output Directory	Notes
Hugo	`hugo`	`public`	Default output directory for Hugo sites
Jekyll	`jekyll build`	`_site`	Builds to `_site` by default
Next.js	`next build`	`.next`	Builds to `.next`, requires static export
Gatsby	`gatsby build`	`public`	Builds to `public` directory
VuePress	`vuepress build`	`.vuepress/dist`	Default output directory for VuePress

Example: Deploying a Hugo Site

pages:
  stage: deploy
  script:
    - hugo
  artifacts:
    paths:
      - public
  only:
    - main

Example: Deploying a Jekyll Site

pages:
  stage: deploy
  script:
    - gem install jekyll
    - jekyll build -d _site
  artifacts:
    paths:
      - _site
  only:
    - main

Note: Ensure that the artifacts path matches the output directory of your static site generator.

Warning: If you're using a custom build command, make sure it outputs to the correct directory as specified in your GitLab CI configuration.

5. Building React/Vue Apps for Pages

Example: Basic React App Build Configuration

pages:
  stage: deploy
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - public
  only:
    - main

Property	Description	Default
pages	Job name for deploying to GitLab Pages	None
stage	Execution stage for the job	`deploy`
script	Commands to build and deploy the app	None
artifacts	Files to be published (e.g., `public` directory)	None

Note: The public directory is the default output path for React and Vue apps built with Create React App or Vue CLI.

Example: Building a Vue App with Custom Output Path

pages:
  stage: deploy
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist
  only:
    - main

React vs Vue Build Process

React: Uses Create React App (CRA) by default, builds to build directory
Vue: Uses Vue CLI, builds to dist directory

6. Configuring SSL for Pages

Example: GitLab Pages with Custom Domain and SSL

pages:
  artifacts:
    paths:
      - public/
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

# Configure custom domain and SSL
pages_domain:
  domain: "docs.example.com"
  ssl_certificate: "/etc/ssl/certs/example.com.crt"
  ssl_key: "/etc/ssl/private/example.com.key"

Property	Description	Values	Notes
pages_domain.domain	Custom domain for GitLab Pages	`string`	Must be a valid domain name
pages_domain.ssl_certificate	Path to SSL certificate file	`string`	Full path to the certificate file
pages_domain.ssl_key	Path to SSL private key file	`string`	Full path to the private key file

Note: SSL certificates must be valid and match the custom domain. GitLab supports both Let's Encrypt and custom SSL certificates.

Warning: Ensure that the certificate and key files are properly secured and accessible to the GitLab Pages service.

7. Using pages:path_prefix

Property	Value	Description
pages:path_prefix	`/docs`	Defines the base path for GitLab Pages deployment.

Example: Setting path_prefix in .gitlab-ci.yml

pages:
  script:
    - mkdir -p public
    - cp -r * public/
  artifacts:
    paths:
      - public
  path_prefix: /docs

Note: The path_prefix is used to define the base path where the Pages will be served from. It's particularly useful when deploying documentation or assets under a specific subdirectory.

8. Setting Pages Access Control

Setting	Description	Values	Notes
pages.access_control	Controls access to GitLab Pages	`public`, `protected`, `private`	Default is `public` unless otherwise configured
pages.protected_access	Enables protected access for Pages	`true`, `false`	Requires `pages.access_control` to be set to `protected`

Example: Configuring Pages Access Control

pages:
  access_control: protected
  protected_access: true

Note: Protected Pages require users to be authenticated to access the content.

Warning: Setting pages.access_control to private restricts access to project members only.

9. Using Pages with Subgroups

Feature	Description	Notes
Subgroup Pages	GitLab Pages can be configured to work within subgroups.	Pages are scoped to the project or subgroup where they're configured.
URL Structure	Pages URL follows the pattern: `https://<group>.gitlab.io/<project>`	Subgroups can have their own custom domain if configured.
Configuration	Pages settings are inherited from the parent group or project.	Subgroup-level configuration overrides project-level settings.

Example: Configuring Pages in a Subgroup

pages:
  service_name: gitlab-pages
  artifacts:
    paths:
      - public/

Note: Pages in subgroups require proper permissions and configuration to ensure the build and deployment process works correctly.

10. Deploying Documentation Sites

Example: Deploying documentation with MkDocs

pages:
  stage: deploy
  script:
    - pip install mkdocs
    - mkdocs build
  artifacts:
    paths:
      - public
  only:
    - main

Property	Description	Default	Notes
pages.script	Script to build documentation site	None	Required for deployment
pages.artifacts	Paths to include in deployment	None	Must contain built site files
pages.only	Branches to deploy from	All branches	Use for selective deployment

Note: GitLab Pages requires the public directory by default for static site deployment.

Warning: Ensure pages.artifacts includes all necessary files (CSS, JS, images) for the documentation site to function correctly.