Handbook Architecture

An overview on how the Handbook is architected

Architecture Overview

The Markdown files get parsed by Hugo, and converted into static HTML files, including all assets (JS, CSS, images, etc.). The static files are uploaded to GitLab Pages.

flowchart TD
    A(docsy) --> B
    B(docsy-gitlab) --> H
    B(docsy-gitlab) --> I
    C(www-gitlab-com) --> H
    C(www-gitlab-com) --> I
    D(handbook) --> H
    E(handbook-internal) --> I
    H{build} --> |Deploy| F
    I{build} --> |Deploy| G
    F[handbook.gitlab.com]
    G[internal.gitlab.com]

There are four internal projects and one external project used in the process of building and deploying the internal and external handbooks.

  1. Docsy is the base theme used for both handbook sites.
  2. Docsy GitLab is an extension to the base Docsy theme with GitLab specific customizations and features. Docsy GitLab is included in both handbook sites.
  3. www-gitlab-com is the source repository of data files used by both handbook sites.
  4. handbook is the public handbook site.
  5. internal-handbook is the internal handbook site.

Templates and Partials

Review the Hugo development documentation to learn more.

There are some partials specific to GitLab.

Access tokens

To minimize maintenance, a small number of group and project access tokens are used. This overview is not meant to be a comprehensive list. Search in this and other development documentation pages for details on the individual access tokens.

  1. GITLAB_TOKEN, currently called Docsy GitLab Release. Used for various things, primarily:
    1. docsy-theme release job
    2. notify handbook jobs
  2. TRIAGE_BOT, currently called Triage bot. Used for various maintenance tasks, primarily:
    1. Triage
    2. CI jobs in maintenance-tasks
  3. Project access tokens are sometimes created for project specific tasks, such as DANGER_GITLAB_API_TOKEN.

A “zap” (internal) (use shared 1Password sign in) has been configured with a group level webhook to notify the #handbook-escalation channel. Due to its reliability, you may want to consider creating an issue, or some other reminder.

Handbook monitoring

The handbook monitor project runs a pipeline every 10 minutes (see pipeline schedule) to check if the handbook is “up” using hurl.

There is another scheduled monthly pipeline that will rebuild the image used in CI. This job will only run if there’s an environment variable REBUILD set to TRUE to avoid rebuilding the image with every scheduled CI job.

If the job fails, the pipeline will post to the #handbook-escalation Slack channel.

Notices are also posted in that channel when pipelines fail on the main branch of the handbook projects.

Note: Internal handbook is not monitored in this way as there is a blocking issue. See internal-handbook#90. Similarly, the request for integrating the handbook to infra’s monitoring is pending. See docsy#14 for more information.

View page source - Edit this page - please contribute. Creative Commons License