doc/user/project/wiki/wiki_for_planning.md
{{< details >}}
{{< /details >}}
GitLab Wiki works with your planning tools. It's not a separate tool. You can link wiki pages to epics, issues, and boards. With embedded views powered by GitLab Query Language (GLQL), your wiki pages can display live, auto-updating views of issues and work items - turning documentation into dynamic dashboards. Learn how to connect wiki with issues, epics, and boards to create a smooth workflow where documentation and planning work together.
A wiki helps your planning tools by giving you:
To use this guide effectively, you should be familiar with:
Create links between wiki documentation and your planning items to build a connected knowledge network.
Epics often need detailed specifications that are too long for an epic description. Keep the full documentation in a wiki:
In the top bar, select Search or go to and find your project.
Select Plan > Wiki.
Create a wiki page with your detailed requirements (for example, with slug product-requirements).
In the top bar, select Search or go to and find your project's group.
Select Plan > Work items.
In the filter bar, select the filter Type, operator is, and value Epic.
Identify your desired epic, and select its title.
In the epic description, link to the wiki page:
## Requirements
See full specification: [[product-requirements]]
Or with custom text: [[Full PRD|product-requirements]]
Or use the full URL:
[Full PRD](https://gitlab.example.com/group/project/-/wikis/product-requirements)
In the wiki page, link back to the epic:
Related epic: &123
Example use cases:
Link issues to wiki pages for implementation details, standards, and guides:
## Implementation notes
Follow our [[API-design-standards]] when implementing this endpoint.
For local setup, see [[Development Setup Guide|development-environment-setup]].
Definition of Done: [[team-dod]]
Example use cases:
Reference issues and epics directly in wiki pages:
## Current sprint goals
- Implement user authentication: #1234
- Fix performance regression: #1235
- Update API documentation: #1236
## Q3 roadmap
Major initiatives:
- Authentication overhaul: &10
- Performance improvements: &11
- API v2 release: &12
Link to wiki pages in other projects:
## Related documentation
See the backend team's API guide: [[backend/api:api-standards]]
Or use the alternative syntax: [wiki_page:backend/api:api-standards]
With custom text: [[Backend API Standards|backend/api:api-standards]]
{{< history >}}
glql_integration. Disabled by default.glql_integration removed.{{< /history >}}
Transform your wiki pages into live dashboards using GitLab Query Language (GLQL). Embedded views automatically update when data changes, providing real-time visibility into your planning data without leaving the wiki.
[!note] Embedded views have performance considerations. Large queries may time out or be rate-limited. If you encounter timeouts, reduce the scope of your query by adding more filters or reducing the
limitparameter.
To embed a GLQL query, use a code block with glql as the language identifier:
```glql
display: table
title: Sprint 18.5 Dashboard
description: Current sprint work items
fields: title, assignee, state, health, labels, milestone, updated
limit: 20
sort: updated desc
query: project = "gitlab-org/gitlab" and milestone = "18.5" and opened = true
```
This creates a live table showing all open issues in the current milestone, automatically updating as issues are created, modified, or closed.
Create comprehensive planning dashboards directly in your wiki pages.
[!note] In the examples throughout this section, replace
project = "group/project"with your actual project path, such asproject = "gitlab-org/gitlab"orproject = "my-team/my-project".
Prerequisites:
Sprint overview dashboard:
```glql
display: table
title: Sprint Overview
description: All work for the current sprint
fields: title, assignee, state, labels("priority::*") as "Priority", health, due
limit: 30
sort: due asc
query: project = "group/project" and milestone = "Current Sprint" and opened = true
```
Critical bugs tracker:
```glql
display: table
title: Critical Bugs
description: High-priority bugs requiring immediate attention
fields: title, assignee, labels, created, updated
limit: 10
query: project = "group/project" and label = "bug" and label = "severity::1" and opened = true
```
Team workload view:
```glql
display: list
title: Team Work In Progress
description: Active work items by team member
fields: title, assignee, milestone, due
limit: 15
sort: assignee asc
query: project = "group/project" and assignee in (alice, bob, charlie) and label = "workflow::in dev"
```
Personal task list:
```glql
display: orderedList
title: My Tasks
description: Tasks assigned to me, sorted by priority
fields: title, labels("priority::*") as "Priority", due
limit: 10
sort: due asc
query: type = Task and assignee = currentUser() and opened = true
```
The embedded views support:
table, list, or orderedListcurrentUser() for personalized views and today() for date-based queriesCreate a connected documentation flow throughout your sprint:
Maintain strategic documentation that connects to your roadmap:
roadmap/
├── 2025-strategy
├── q1-okrs
├── q2-okrs
├── architecture-decisions/
│ ├── adr-001-microservices
│ ├── adr-002-authentication
└── technical-debt-registry
Each page links to relevant epics and tracks progress through issue references.
Document technical decisions with traceability. You can use a template similar to this:
# ADR-001: Adopt microservices architecture
## Status
Accepted
## Context
[Detailed context...]
## Decision
[Decision details...]
## Consequences
[Impact analysis...]
## Implementation
- Infrastructure epic: &50
- Service extraction: #2001, #2002, #2003
- Monitoring setup: #2004
Use wiki as a collaboration hub for cross-functional teams:
Include wiki references in your templates:
## Prerequisites
- [ ] Review [[contribution-guidelines]]
- [ ] Check [[security-checklist]]
- [ ] Read relevant documentation in [[project-wiki-home]]
## Implementation
- [ ] Follow [[coding-standards]]
- [ ] Update [[api-documentation]] if needed
- [ ] Add tests per [[testing-guidelines]]
Link to wiki planning documents:
## Milestone 18.5
Sprint dates: 2025-02-01 to 2025-02-14
- [[Sprint 18.5 Goals|sprint-18-5-goals]]
- [[Sprint 18.5 Capacity|sprint-18-5-capacity]]
- [[Known Issues|known-issues-and-workarounds]]
Reference wiki workflow documentation:
This board follows our [[Kanban Workflow Guide|kanban-workflow-guide]].
For column definitions, see [[Board Column Definitions|board-column-definitions]].
Build wiki pages that collect related issues:
# Open bugs dashboard
## Critical (P1)
- #1001 - Database connection timeout
- #1002 - Authentication bypass
## High (P2)
- #1003 - Performance degradation
- #1004 - UI rendering issue
## By component
### Authentication
- #1001, #1005, #1009
### API
- #1002, #1006, #1010
Organize wiki pages with folders and relative links:
# Team handbook
## Processes
- [Sprint Planning](processes/sprint-planning) - How we plan sprints
- [Code Review](processes/code-review) - Review standards and SLAs
- [Incident Response](processes/incident-response) - On-call procedures
## Go up to parent page
[Back to Documentation](../documentation)
A complete feature development cycle using wiki integration:
Product Manager:
feature-x-prd wiki page with market research.[[Feature X PRD|feature-x-prd]].Engineering Lead:
feature-x-technical-design wiki page.Engineers:
QA Engineer:
feature-x-test-plan wiki page.Technical Writer:
Structure your team handbook with embedded views for real-time insights:
# Engineering team handbook
## Current sprint status
```glql
display: table
title: Sprint Progress
fields: title, assignee, state, labels("workflow::*") as "Status"
limit: 20
query: project = "team/project" and milestone = "Sprint 23" and opened = true
```
## Processes
- [[Sprint Planning Process|sprint-planning-process]] - How we plan sprints
- [[Code Review Guidelines|code-review-guidelines]] - Review standards and SLAs
- [[Incident Response|incident-response]] - On-call procedures
## Technical standards
- [[API Design Standards|API-design-standards]] - REST API conventions
- [[Database Schema Guide|database-schema-guide]] - Schema design rules
- [[Security Checklist|security-checklist]] - Security requirements
## Work management
- [Issue board](https://gitlab.example.com/group/project/-/boards/123)
- [Current milestone](https://gitlab.example.com/group/project/-/milestones/45)
- Label taxonomy: [[Label Definitions|label-definitions]]
## Onboarding
- [[New Developer Setup|new-developer-setup]] - Environment setup
- [[First Week Issues|first-week-issues]] - Good first issues: #101, #102, #103
- [[Team Contacts|team-contacts]] - Who to ask for what
| Purpose | Syntax | Example |
|---|---|---|
| Link to wiki page (same project) | [[page-slug]] | [[api-standards]] |
| Link with custom text | [[Display Text|page-slug]] | [[our API guide|api-standards]] |
| Cross-project wiki link | [[group/project:page-slug]] | [[backend/api:rest-guide]] |
| Alternative wiki syntax | [wiki_page:page-slug] | [wiki_page:home] |
| Cross-project alternative | [wiki_page:namespace/project:page-slug] | [wiki_page:backend/api:home] |
| Hierarchical link (same level) | [Link text](page-slug) | [Related](related-page) |
| Hierarchical link (parent) | [Link text](../parent-page) | [Up](../main) |
| Hierarchical link (child) | [Link text](child-page) | [Details](details) |
| Root link | [Link text](/page-from-root) | [Home](/home) |
| Full URL | Standard Markdown | [API Guide](https://gitlab.example.com/.../wikis/api-standards) |
| Item type | Syntax | Example |
|---|---|---|
| Issue (same project) | #123 | #123 |
| Issue (different project) | group/project#123 | gitlab-org/gitlab#123 |
| Merge request | !123 | !123 |
| Epic | &123 | &123 |
| Milestone | %"Milestone Name" | %"18.5" |
Use task lists in wiki that can be converted to issues:
## Action items from retrospective
- [ ] Improve CI pipeline performance
- [ ] Update documentation
- [ ] Add monitoring for API endpoints
Select the checkboxes and use Create issue to convert tasks to tracked issues.
api-standards not API Standards.sprint-2025-01, adr-001, feature-name.archive/ folder.Create wiki templates for common documents: