Knowledge Base Article Creation Workflow

How Support Engineers create and publish knowledge base articles, including the AI-assisted human-in-the-loop workflow.

This page explains how Support Engineers create knowledge base articles and get them published. Articles are authored in the articles sync repository (master branch) and automatically synced to the GitLab Support Portal and the U.S. Government Support Portal.

For background on when to write a knowledge article versus updating product documentation, see Docs vs. Knowledge Articles.

Entry points

There are two main ways to start creating an article:

AI-assisted workflow - use the Glean Ticket to KB planning agent or the /create-kb skill to draft an article from a support ticket, then review and submit it through the articles repo. This is the recommended path when working from a resolved ticket.
Manual workflow - create the article directly in the articles repo using the Web IDE. Use this path for articles not tied to a specific ticket, or when you prefer to write from scratch.

Both paths converge at the same articles repo MR process and require the same human review before publication.

AI-assisted workflow (human-in-the-loop)

The AI-assisted workflow has two stages: a planning stage and a build stage.

Stage 1: Planning (Glean Ticket to KB agent or /create-kb skill)

The planning stage uses AI to draft article content from a support ticket. You remain in control throughout - the AI produces a draft that you review and approve before anything is committed.

What the planning agent does:

Reads the ticket content and proposes an article title, type, section, and body draft.
Checks for duplicate titles across the articles repo before proposing a title.
Flags potential duplicates so you can decide whether to create a new article or update an existing one.

Your responsibilities at this stage:

Review the proposed title, type, section, and body for accuracy and completeness.
Confirm the article does not duplicate an existing one.
Check that the content is appropriate for the target audience:
- Set public: true for customer-facing articles; public: false for internal-only articles.
- Remove the US Government instance if the article does not apply to U.S. Government customers, or remove Global if it applies only to U.S. Government.
- Do not include internal links (Zendesk tickets, internal issues, Slack threads) in customer-facing articles.
Approve the draft before the build stage begins.

The planning agent does not commit or create MRs. It produces a plan that you must explicitly approve before the build stage runs.

Stage 2: Build (Duo Developer flow)

Once you approve the plan, the Duo Developer flow creates a branch in the articles repo, commits the article file, and opens a merge request using the “New KB Article” MR template. The MR targets the master branch.

What the build agent does:

Creates the article file at Knowledge Articles/<section>/<Article Title>.md.
Populates frontmatter from the approved plan.
Sets product_categories: [] - this field is populated automatically by Duo Developer. It can be set using by requesting a review from @ai-support-knowledge-base-triage-flow-gitlab-com

Your responsibilities at this stage:

Review the opened MR and verify the article content, frontmatter, and file placement are correct.
Request a review from a Knowledge Champion once the triage flow has run.

Manual workflow

If you are not using the AI-assisted workflow, create the article directly in the articles repo:

Open the articles repo in your IDE of choice, or the Web IDE (press . on your keyboard).
Search the existing knowledge base to confirm no article already covers the issue:
- Global knowledge base
- U.S. Government knowledge base
In the Explorer panel, open Knowledge Articles > Templates and copy the template for your article type (see Article types below).
Navigate to Knowledge Articles > <your section> and create a new file. Name it to closely match your article title with a .md extension.
Paste the template content, update the frontmatter, and write the article body.
Commit and open an MR targeting master using the “New KB Article” MR template.

Article types

Choose the template that best matches your content. Templates are in Knowledge Articles/Templates/.

Type	Template file	Use when
Break/Fix	`breakfix.md`	A specific issue needs an immediate fix with a direct solution
FAQ	`faq.md`	Answering a common question
How-To	`how-to.md`	Providing step-by-step instructions for a task
Process	`process.md`	Documenting an internal process
Troubleshooting	`troubleshooting.md`	Diagnosing and resolving issues, focusing on root cause

The article type does not need to match the section. For example, a Break/Fix article about an error goes in the Errors section.

Sections

Each article belongs to one section, which determines its directory in the repo:

Administrative
AI
Agile Planning
CI/CD Pipeline & Runner
CoreDevOps
Errors
How-To
Infrastructure
Kubernetes
Licensing & Subscription
Migrations
Observability
Other Articles
Performance
R&D TPM
Security
Security and Compliance
Support Pages
Troubleshooting
Upgrades

Frontmatter requirements

Every article must start with YAML frontmatter. The authoritative field definitions and validation rules are in the articles repo README and AGENTS.md.

---
title: 'Your Unique Article Title'
previous_title: 'Your Unique Article Title'
category: 'Knowledge Articles'
section: 'Errors'
author: 'your-gitlab-handle'
tags: []
labels: []
instances:
- Global
- US Government
public: true
convert_markdown: true
source: 'https://gitlab.zendesk.com/agent/tickets/TICKET_NUMBER'
product_categories: []
---

Key rules (enforced by CI - see Validation):

title must be unique across the entire repository. Check before creating.
previous_title must match title (differs only when renaming an existing article).
section must match the directory you placed the file in. Change it from 'Templates'.
instances must include at least one value: Global, Global Sandbox, US Government, or US Government Sandbox.
public controls visibility: true for customer-facing, false for internal-only. Internal articles show a lock icon in the support portal.
convert_markdown must be true for all new articles.
product_categories must be []. The KB Triage Agentic Flow populates this automatically.
public and convert_markdown must be booleans (true/false), not quoted strings.

Privacy and data classification

Before setting public: true, confirm the article contains no:

Customer-identifying information (names, email addresses, organization details).
Internal links that customers cannot access (Zendesk ticket URLs, internal issues, Slack threads).
Information classified as internal under the SAFE framework.

If any of these apply, either remove the sensitive content or set public: false.

Article body

Follow the section structure from your chosen template. Every article must include at minimum:

Description (or Overview / Introduction, depending on type) - describe the symptoms, task, or situation. Include the exact error message a user would see, as text (not a screenshot), to aid searchability.

Impacted Offerings - list the affected GitLab offerings:

## Impacted Offerings

- GitLab.com
- GitLab Dedicated
- GitLab Self-Managed

Solution / Resolution / Instructions - the primary content section.

For formatting guidance, see the Knowledge Base Style Guide.

Validation

The articles repo CI pipeline runs two checks on every MR:

check_repo_files (blocking) - validates frontmatter fields, types, allowed values, unique titles, and file placement. If it fails, a comment is posted on the MR with details. Fix the reported errors and push again.
check_triage_reviewer (blocking) - verifies that the KB Triage Agentic Flow (@ai-support-knowledge-base-triage-flow-gitlab-com) has run on the MR and populated product_categories. If the triage flow has not run, the pipeline fails with instructions to request a review from the bot.

To request the triage flow to run, post the following in an MR comment:

/request_review @ai-support-knowledge-base-triage-flow-gitlab-com

Note for Duo Developer flow MRs: If the Duo Developer flow created the MR (branch starts with duo/ and Duo Developer authored a commit), the triage reviewer requirement is waived automatically.

You can run frontmatter validation locally before pushing:

gem install bundler && bundle install
./bin/check_validity

Knowledge Champion review

Before an article can be merged, a human reviewer from the Article Publishers / Knowledge Champions group must approve it. The reviewer checks:

Technical accuracy and completeness.
Formatting consistency with the article template.
That all links are valid and publicly accessible (for public articles).
That product_categories has been populated by the triage flow.

If changes are needed, the MR is assigned back to you. Once approved, the reviewer merges the MR and the article is published automatically to the support portal.

For the full review process, see Knowledge Article Review Process.

Duplicate and evidence safeguards

Before creating an article, verify that no existing article covers the same issue:

Search the Global knowledge base and U.S. Government knowledge base.
Check the articles repo for articles with similar titles or content.
The CI check_repo_files job enforces unique titles across the repository and will block merge if a duplicate title is detected.

If a similar article exists, consider updating it rather than creating a new one. Use the “Existing KB Article” MR template for updates.

Troubleshooting

CI fails with frontmatter errors

The check_repo_files job posts a comment on the MR listing the specific errors. Common causes:

section still set to 'Templates' - change it to match your target directory.
public or convert_markdown set as a quoted string ("true") - use the boolean true.
instances is empty - add at least one value.
Duplicate title - choose a unique title.

CI fails with missing triage reviewer

The check_triage_reviewer job fails if the KB Triage Agentic Flow has not run. Post the following in an MR comment to request a review:

/request_review @ai-support-knowledge-base-triage-flow-gitlab-com

If the triage flow ran but product_categories is still empty, retry the review request.

Article not appearing in the knowledge base after merge

Articles are synced automatically after merge. If an article does not appear within a reasonable time, post in #spt_knowledge-base.

Getting help

Post questions in #spt_knowledge-base. For training resources, see Knowledge Base Training Resources.

Last modified October 7, 2026: Add Knowledge Base article creation workflow handbook page (8251bfd0)

View page source - Edit this page - please contribute.