Add Knowledge Base article creation workflow handbook page

---

title: Knowledge Base Article Creation Workflow

description: 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](https://gitlab.com/gitlab-com/support/articles)

(`master` branch) and automatically synced to the

[GitLab Support Portal](https://support.gitlab.com/hc/en-us/sections/15215649512604-Knowledge-Base)

and the [U.S. Government Support Portal](https://federal-support.gitlab.com/hc/en-us/sections/29015014994068-Knowledge-Base).

For background on when to write a knowledge article versus updating product documentation, see

[Docs vs. Knowledge Articles](/handbook/support/knowledge-base/docs-vs-kb/).

## 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](#knowledge-champion-review) 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:

1. Open the [articles repo](https://gitlab.com/gitlab-com/support/articles) in your IDE of choice,

   or the Web IDE (press `.` on your keyboard).

1. Search the existing knowledge base to confirm no article already covers the issue:

   - [Global knowledge base](https://support.gitlab.com/hc/en-us/sections/15215649512604-Knowledge-Base)

   - [U.S. Government knowledge base](https://federal-support.gitlab.com/hc/en-us/sections/29015014994068-Knowledge-Base)

1. In the Explorer panel, open `Knowledge Articles > Templates` and copy the template for your

   article type (see [Article types](#article-types) below).

1. Navigate to `Knowledge Articles > <your section>` and create a new file. Name it to closely

   match your article title with a `.md` extension.

1. Paste the template content, update the frontmatter, and write the article body.

1. 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](https://gitlab.com/gitlab-com/support/articles/-/blob/master/README.md)

and [AGENTS.md](https://gitlab.com/gitlab-com/support/articles/-/blob/master/AGENTS.md).

```yaml

---

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](#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](/handbook/legal/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:

  ```markdown

  ## 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](/handbook/support/knowledge-base/kb-style-guide/).

## Validation

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

1. **`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.

1. **`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:

```plaintext

/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:

```shell

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](https://gitlab.com/groups/gitlab-com/support/article-publishers/-/group_members?with_inherited_permissions=exclude)

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](/handbook/support/knowledge-base/article-review/).

## Duplicate and evidence safeguards

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

- Search the [Global knowledge base](https://support.gitlab.com/hc/en-us/sections/15215649512604-Knowledge-Base)

  and [U.S. Government knowledge base](https://federal-support.gitlab.com/hc/en-us/sections/29015014994068-Knowledge-Base).

- Check the [articles repo](https://gitlab.com/gitlab-com/support/articles) 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.

## Other ways to request an article

If you prefer not to create the article yourself:

- **Slack**: Post in [#spt_knowledge-base](https://gitlab.enterprise.slack.com/archives/C07QDCG4AGH)

  and tag the Knowledge team. Attach a completed template from the

  [Google Drive templates folder](https://drive.google.com/drive/folders/1hpHAB51x49bRS1tfUqxiQ56UnlITtFHR).

- **Support Team Meta issue**: Open an issue in

  [support-team-meta](https://gitlab.com/gitlab-com/support/support-team-meta/-/issues) using

  the `knowledge-base-article-request` template.

- **Articles repo issue**: Open an issue in the

  [articles repo](https://gitlab.com/gitlab-com/support/articles/-/work_items) using the

  `knowledge-base-article-request` template.

- **Slack command**: Use `/gitlab gitlab-com/support/articles issue new` in any Slack channel.

## 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:

```plaintext

/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](https://gitlab.enterprise.slack.com/archives/C07QDCG4AGH).

## Getting help

Post questions in [#spt_knowledge-base](https://gitlab.enterprise.slack.com/archives/C07QDCG4AGH).

For training resources, see [Knowledge Base Training Resources](/handbook/support/knowledge-base/knowledge-base-training/).