Gitlab Pipeline – pages – What is pages in GitLab CI/CD?

DevOps

MOTOSHARE 🚗🏍️
Turning Idle Vehicles into Shared Rides & Earnings

From Idle to Income. From Parked to Purpose.
Earn by Sharing, Ride by Renting.
Where Owners Earn, Riders Move.
Owners Earn. Riders Move. Motoshare Connects.

With Motoshare, every parked vehicle finds a purpose. Owners earn. Renters ride.
🚀 Everyone wins.

Start Your Journey with Motoshare

GitLab Pages allows you to publish static websites directly from a GitLab repository. The content for these sites is generated and deployed via a specific CI/CD job conventionally named pages.


Example .gitlab-ci.yml for GitLab Pages:

This example will create a very simple static HTML page and deploy it.

YAML

# .gitlab-ci.yml

stages:
  - deploy # A stage for the pages deployment job

# This is the special job that GitLab Pages looks for.
# It must be named 'pages'.
pages:
  stage: deploy
  image: alpine:latest # A lightweight image is sufficient for this simple example

  script:
    - echo "--- Generating static site for GitLab Pages ---"
    # 1. Create the directory GitLab Pages expects for site content
    #    This directory MUST be named 'public'.
    - mkdir -p public

    # 2. Create some static content.
    #    In a real project, this step would involve running a static site generator
    #    (like Jekyll, Hugo, MkDocs, VuePress, Gatsby, or just copying HTML/CSS/JS files).
    - echo '<!DOCTYPE html>' > public/index.html
    - echo '<html lang="en">' >> public/index.html
    - echo '  <head>' >> public/index.html
    - echo '    <meta charset="UTF-8">' >> public/index.html
    - echo '    <meta name="viewport" content="width=device-width, initial-scale=1.0">' >> public/index.html
    - echo '    <title>My GitLab Pages Site</title>' >> public/index.html
    - echo '    <style>' >> public/index.html
    - echo '      body { font-family: sans-serif; display: flex; justify-content: center; align-items: center; height: 100vh; margin: 0; background-color: #f0f0f0; }' >> public/index.html
    - echo '      .container { text-align: center; padding: 20px; background-color: white; border-radius: 8px; box-shadow: 0 4px 8px rgba(0,0,0,0.1); }' >> public/index.html
    - echo '      h1 { color: #333; }' >> public/index.html
    - echo '      p { color: #555; }' >> public/index.html
    - echo '    </style>' >> public/index.html
    - echo '  </head>' >> public/index.html
    - echo '  <body>' >> public/index.html
    - echo '    <div class="container">' >> public/index.html
    - echo '      <h1>Hello from GitLab Pages!</h1>' >> public/index.html
    - echo "      <p>This site was deployed on: $(date)</p>" >> public/index.html
    - echo '      <p>Deployed from commit: <a href="${CI_PROJECT_URL}/-/commit/${CI_COMMIT_SHA}">${CI_COMMIT_SHORT_SHA}</a> on branch <em>${CI_COMMIT_REF_NAME}</em>.</p>' >> public/index.html
    - echo '    </div>' >> public/index.html
    - echo '  </body>' >> public/index.html
    - echo '</html>' >> public/index.html

    # You can create more files and subdirectories within 'public/'
    - mkdir -p public/about
    - echo "<h1>About Us</h1><p>This is the about page.</p><a href='../'>Home</a>" > public/about/index.html

    - echo "Static site content generated in 'public/' directory."

  artifacts:
    paths:
      # 3. This path MUST be 'public'. GitLab Pages serves files from this directory.
      - public
    expire_in: 1 week # Optional: How long to keep the job artifacts

  rules:
    # 4. Deploy GitLab Pages only when pushing to the default branch (e.g., main or master)
    #    Adjust $CI_DEFAULT_BRANCH if your default branch has a different name.
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
      when: on_success # Run only if the script succeeds

Code language: PHP (php)

Explanation:

  1. Job Naming (pages):
    • The job responsible for deploying to GitLab Pages must be named pages. This is a special convention that GitLab recognizes.
  2. stage: deploy:
    • While you can name your stage anything, deploy is a common and logical choice for a job that deploys a website.
  3. image: alpine:latest:
    • For this very simple example of echoing HTML content, a lightweight image like alpine is sufficient.
    • In real-world scenarios, you would use an image that contains your static site generator (e.g., ruby for Jekyll, an image with Node.js for Gatsby/VuePress, python for MkDocs, or a specific image like klakegg/hugo).
  4. script: Section:
    • mkdir -p public: This command creates a directory named public. All the static content (HTML, CSS, JavaScript, images, etc.) that you want to publish must be placed inside this public directory.
    • echo ... > public/index.html: These lines are a simple way to create a basic index.html file inside the public directory. In a real project, this section would contain commands to:
      • Install dependencies for your static site generator (e.g., npm install, bundle install, pip install -r requirements.txt).
      • Run the build command of your static site generator (e.g., hugo, jekyll build, npm run build, mkdocs build). This command typically outputs the static site into a specific folder (like _site, dist, build, site), which you would then need to copy or move into the public directory.
      • Example for a hypothetical generator: YAML# script: # - npm install # - npm run build # Assume this outputs to a './dist' folder # - rm -rf public # Clean up previous content if any # - mv dist public # Move the generated site to 'public'
  5. artifacts: Section:
    • This is a critical part of the pages job.
    • paths: - public: This tells GitLab to take the entire contents of the public directory and save it as job artifacts. GitLab Pages then uses these specific artifacts from the latest successful pages job on the appropriate branch to serve your website.
    • expire_in: 1 week: (Optional) Specifies how long the job artifacts should be kept. For GitLab Pages, the artifacts are used for deployment and are not typically needed for long-term storage in the job artifacts section itself, as the deployed site persists.
  6. rules: Section:
    • - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH': This rule ensures that the pages job (and thus the website deployment) only runs when changes are pushed or merged to the default branch of your repository (commonly main or master). This prevents deploying every commit from feature branches.
    • when: on_success: The job will only proceed if the script commands are successful.

How GitLab Pages Works with This Job:

  1. When you commit changes to your default branch (as defined in the rules), the GitLab CI pipeline triggers.
  2. The pages job runs.
  3. The script section generates your static site content and places it in the public directory.
  4. The artifacts section uploads the public directory.
  5. GitLab takes these artifacts and deploys them to a web server.
  6. Your static site becomes available at a URL typically structured like:
    • For projects under your username: https://<username>.gitlab.io/<projectname>
    • For projects within a group: https://<groupname>.gitlab.io/<projectname>
    • If you’ve configured a custom domain, it will be available at that domain.

You can find the exact URL for your GitLab Pages site in your project’s Settings > Pages section after the first successful deployment.

This basic example provides the fundamental structure. You would replace the echo commands with the actual build process for your chosen static site generator.

Subscribe
Notify of
guest

This site uses Akismet to reduce spam. Learn how your comment data is processed.

0 Comments
Oldest
Newest Most Voted
Inline Feedbacks
View all comments
0
Would love your thoughts, please comment.x