GitLab Documentation

Automated Documentation with Sphinx

1. Create a .gitlab-ci.yml file if it does not already exist.

2. Add a job for generating documentation. For example:

   stages:
       - build
       - docs
   
   generate_docs:
       stage: docs
       image: sphinxdoc/sphinx
       script:
       - sphinx-build -b html source/ build/html
       artifacts:
       paths:
           - build/html
   

3. Configure your pipeline to trigger the documentation generation job on relevant events, such as merging to the main branch or tagging a release.

4. Use GitLab Pages to host and serve your generated documentation publicly or within your team.

Configure a GitLab Pages job in your pipeline to publish the generated documentation:

  pages:
    stage: deploy
    script:
      - mv build/html public
    artifacts:
      paths:
        - public

Use Hugo Framework with GitLab Pages

1. Prerequisites: Download and install Hugo from the official Hugo website .

2. Create a New Hugo Site:

   hugo new site my-hugo-site
   cd my-hugo-site
   

3. (Optional) Choose a theme from the Hugo Themes site and add it as a Git submodule.

   git init
   git submodule add https://github.com/theme/your-chosen-theme.git themes/your-chosen-theme
   echo 'theme = "your-chosen-theme"' >> config.toml
   

4. Create a .gitlab-ci.yml file in the root of your project to set up the CI/CD pipeline.

   Hugo pipeline in next gen ci/cd

5. Once the pipeline completes successfully, your Hugo site will be available at the link at Deploy > Pages > Deployments.

And that’s it! You now have a Hugo site hosted on GitLab Pages.

Use Docusaurus and deploy with GitLab Pages

1. Prerequisites: Ensure you have Node.js and Yarn installed on your machine.

2. Create a New Docusaurus Site

       npx create-docusaurus@latest my-docusaurus-site classic
       cd my-docusaurus-site
   

3. Create a .gitlab-ci.yml file in the root of your project to set up the CI/CD pipeline.

   image: node:latest
   
   cache:
       paths:
       - node_modules/
   
   before_script:
       - yarn install
   
   pages:
       script:
       - yarn build
       - cp -r build public
       artifacts:
       paths:
           - public
       only:
       - master
   

4. Once the pipeline completes successfully, your Docusaurus site will be available at the link at Deploy > Pages > Deployments.

And that’s it! You now have a Docusaurus site hosted on GitLab Pages.

Control GitLab Pages Visibility

GitLab Pages can be configured to have different visibility settings to control who can see the published content.

1. Access Control at Project Level:

   • Go to your GitLab project.
   • Navigate to Settings > General > Visibily, project features, permissions > Pages.
   • Choose one of the following visibility options:
     • Everyone: Your GitLab Pages site will be accessible to anyone. Even not logged visitors. It is generally recommended to use ‘Everyone with access’ for internal documentation cases.
     • Only Project Members: Restrict the access to your GitLab Pages site to only project members.
     • Everyone With Access: Anyone logged into GitLab can browse the website, regardless of their project membership.

2. Using GitLab CI/CD Configuration for Further Control:

   • Edit your project’s .gitlab-ci.yml file to specify access controls.
   • You can define advanced access configurations directly within the CI/CD configuration.

Here is an example snippet for your .gitlab-ci.yml:

pages:
  script:
    - mkdir .public
    - echo "Your website content" > .public/index.html
  artifacts:
    paths:
      - .public
  only:
    - master
  variables:
    CI_PAGES_RESTRICTED: "true"

Setting CI_PAGES_RESTRICTED to true will restrict the pages access to only authenticated users.