Wiki Sync Guide - Using BuildKit Commands

This guide documents the proper way to sync wiki content across repositories using BuildKit CLI commands. These are the recommended, production-ready approaches that handle multi-repo operations correctly.

Overview

Instead of using shell scripts (which are discouraged), BuildKit provides native TypeScript-based commands for syncing wiki content across repositories. These commands ensure proper error handling, metadata preservation, and transactional consistency.

Available BuildKit Wiki Sync Commands

1. Basic Wiki Management

Create Wiki Page

buildkit wiki create "Page Title" --content "Your content here"

Options:

-c, --content <text> - Page content (inline)
-p, --project <id> - Project ID (defaults to $GITLAB_PROJECT_ID)

Example:

buildkit wiki create "API Documentation" \
  --content "$(cat docs/api.md)" \
  --project "my-group/my-project"

Edit Existing Wiki Page

buildkit wiki edit "page-slug"

Options:

-c, --content <text> - New content to replace
-p, --project <id> - Project ID

Example:

buildkit wiki edit "api-documentation" \
  --content "Updated content" \
  --project "my-group/my-project"

List All Wiki Pages

buildkit wiki list

Options:

--with-content - Include full page content in output
-p, --project <id> - Project ID

Example:

buildkit wiki list --with-content --project "my-group/my-project"

Search Wiki Pages

buildkit wiki search "query"

Example:

buildkit wiki search "authentication" --project "my-group/my-project"

2. Migrate Markdown Files to Wiki

Bulk Migration (Recommended)

buildkit wiki migrate-all

Options:

--dry-run - Preview migration without executing
-s, --source <path> - Source directory to scan (default: current directory)
-p, --project <id> - Target project ID

Examples:

Preview migration:

buildkit wiki migrate-all --dry-run --source ./docs

Execute migration:

buildkit wiki migrate-all --source ./docs --project "my-group/my-project"

Behavior:

Automatically scans for .md files
Filters out protected files (README.md, CHANGELOG.md, .gitlab/* files)
Converts filenames to page titles
Creates or updates pages in GitLab Wiki
Preserves original markdown formatting

3. Sync Between Repositories

Sync Wiki Pages Only

buildkit gitlab sync wiki \
  --primary-project "primary/project" \
  --secondary-project "secondary/project"

Options:

--primary-project <id> - Source repository
--secondary-project <id> - Target repository
--pages <pages> - Comma-separated list of page slugs, or "all"
--dry-run - Preview changes without applying
--config <path> - Path to sync configuration (default: .gitlab/sync-config.yaml)

Examples:

Sync specific pages:

buildkit gitlab sync wiki \
  --primary-project "docs/main" \
  --secondary-project "docs/backup" \
  --pages "home,api-reference,getting-started"

Sync all pages:

buildkit gitlab sync wiki \
  --primary-project "docs/main" \
  --secondary-project "docs/backup" \
  --pages "all"

Dry run to preview:

buildkit gitlab sync wiki \
  --primary-project "docs/main" \
  --secondary-project "docs/backup" \
  --dry-run

Sync All Repository Data (Issues, Milestones, Wiki)

buildkit gitlab sync all \
  --primary-project "primary/project" \
  --secondary-project "secondary/project"

Options:

Same as above, syncs issues, milestones, AND wiki pages

Features:

Preserves all metadata (dates, descriptions, issue assignments)
Handles conflict detection and resolution
Supports full metadata preservation mode
Provides detailed sync reporting

4. Continuous Documentation Sync

For automated, continuous synchronization of documentation to the Technical Bible Wiki:

buildkit sync-docs --once

Options:

--once - Run single sync instead of continuous mode
--interval <ms> - Sync interval in milliseconds (default: 3600000 = 1 hour)

Example - Single run:

buildkit sync-docs --once

Example - Continuous mode (1 hour interval):

buildkit sync-docs --interval 3600000

Output includes:

Number of action items found
Outdated documentation sections
Documentation gaps identified
Wiki pages updated count

Configuration

Project ID Resolution

BuildKit automatically resolves project IDs using this priority:

Command-line option: --project "group/project" or --project "123"
Environment variable: GITLAB_PROJECT_ID or GITLAB_PROJECT_PATH
Default: agentstudio/agent-buildkit (for wiki commands)

Sync Configuration File

For multi-repo syncs, create .gitlab/sync-config.yaml:

# Example sync configuration
primary_project: "docs/main"
secondary_projects:
  - "docs/backup"
  - "docs/archive"

sync_rules:
  - type: wiki
    pages:
      - "home"
      - "api-reference"
      - "getting-started"
  - type: issues
    labels:
      - "documentation"
  - type: milestones
    include_issues: true
    preserve_metadata: true

conflict_resolution:
  strategy: "primary-wins"  # or "merge" or "manual"
  auto_resolve: true

Common Workflows

Workflow 1: Migrate All Project Docs to Wiki

Problem: Multiple .md files scattered across the repository.

Solution:

# 1. Preview what will be migrated
buildkit wiki migrate-all --dry-run --source ./docs

# 2. If satisfied, execute migration
buildkit wiki migrate-all --source ./docs

# 3. Verify all pages created
buildkit wiki list --project "my-group/my-project"

# 4. Delete original .md files after verification
rm -rf ./docs/*.md

Workflow 2: Keep Two Wiki Repos in Sync

Problem: Need to maintain mirror documentation in two GitLab projects.

Solution:

# One-time initial sync
buildkit gitlab sync wiki \
  --primary-project "docs/primary" \
  --secondary-project "docs/backup" \
  --dry-run

# If satisfied:
buildkit gitlab sync wiki \
  --primary-project "docs/primary" \
  --secondary-project "docs/backup"

# For continuous syncing, use CI/CD pipeline (see below)

Workflow 3: Update Documentation in Primary, Sync to Secondary

Problem: Documentation changes in primary repo should auto-sync to secondary.

CI/CD Pipeline Configuration (.gitlab-ci.yml):

sync-wiki-pages:
  stage: deploy
  script:
    - buildkit gitlab sync wiki \
        --primary-project "docs/primary" \
        --secondary-project "docs/backup"
  only:
    - main
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN

Workflow 4: Continuous Sync to Technical Bible

Problem: Need to maintain a central documentation wiki that aggregates content from multiple projects.

Solution:

# Run as a scheduled CI/CD job
buildkit sync-docs --once

CI/CD Schedule Configuration (every hour):

continuous-doc-sync:
  stage: documentation
  script:
    - buildkit sync-docs --once
  variables:
    GITLAB_TOKEN: $CI_JOB_TOKEN
  only:
    - schedules

Error Handling

Common Errors and Solutions

Error: "Project not found"

Cause: Invalid project ID or insufficient permissions

Solution:

# Verify project ID format
buildkit wiki list --project "group/project"

# Check GitLab token permissions
echo $GITLAB_TOKEN

# Ensure GITLAB_TOKEN is set
export GITLAB_TOKEN="your-token-here"

Error: "Page already exists"

Cause: Creating a page that already exists

Solution:

Use buildkit wiki edit instead of create
Or use buildkit gitlab sync wiki with update mode

Error: "Sync conflict detected"

Cause: Both repositories have different versions of the same page

Solution:

# Preview the conflict
buildkit gitlab sync wiki --dry-run

# Check conflict resolution strategy in .gitlab/sync-config.yaml
# Options: "primary-wins", "merge", "manual"

Best Practices

1. Always Use Dry-Run First

# Always preview before executing
buildkit wiki migrate-all --dry-run
buildkit gitlab sync wiki --dry-run
buildkit sync-docs --once  # First run to test

2. Verify Permissions

Ensure GITLAB_TOKEN has api scope
Token must have write access to target projects
Use CI/CD job tokens for automated syncs: $CI_JOB_TOKEN

3. Use GitLab Wiki as Single Source of Truth

Delete .md files after migration
Edit wiki pages directly via buildkit wiki edit
Don't maintain dual sources (wiki + .md files)

4. Configuration Management

Store sync configuration in .gitlab/sync-config.yaml
Commit configuration to version control
Use environment variables for sensitive data
Document custom sync rules for team

5. Monitoring and Logging

Check CI/CD job logs for sync operations
Verify page creation in GitLab UI
Monitor wiki page update timestamps
Set up alerts for failed syncs

6. Content Organization

Use consistent naming conventions
Group related pages with hierarchical slugs
Add navigation links between pages
Include metadata in page headers

Advanced Features

Metadata Preservation

When syncing between repos, BuildKit preserves:

Page creation and update timestamps
Author information
Issue associations
Milestone information
Page format (Markdown, AsciiDoc, etc.)

Conflict Resolution

BuildKit supports multiple conflict resolution strategies:

primary-wins: Primary repo version overrides secondary
merge: Intelligent merge of changes
manual: Requires manual review before syncing

Search Functionality

Find content across all wiki pages:

buildkit wiki search "keyword" --project "my-group/my-project"

Returns:

Page title
Page slug
Content snippet with keyword highlighted

Troubleshooting

Wiki Pages Not Syncing

Check:

Verify project IDs are correct: buildkit wiki list
Run with --dry-run first
Check GitLab token: echo $GITLAB_TOKEN
Review CI/CD logs for detailed error messages

Metadata Lost During Sync

Solution: Use --preserve-metadata flag:

buildkit gitlab sync milestones \
  --preserve-metadata \
  --primary-project "primary/project" \
  --secondary-project "secondary/project"

Slow Sync Performance

For large wikis with many pages:

# Sync specific pages instead of all
buildkit gitlab sync wiki \
  --pages "page1,page2,page3" \
  --primary-project "primary/project" \
  --secondary-project "secondary/project"

buildkit wiki - Wiki page management
buildkit gitlab sync - Multi-repo synchronization
buildkit sync-docs - Continuous documentation sync
buildkit gitlab sync issues - Sync issues between repos
buildkit gitlab sync milestones - Sync milestones with metadata

Support

For issues or questions about wiki sync:

Check BuildKit repository: https://gitlab.com/blueflyio/agent-buildkit
Review issue tracker: https://gitlab.com/blueflyio/agent-buildkit/-/issues
Check this guide: $LLM_ROOT/technical-documentation/deployment-and-operations/wiki-sync.md

Wiki Sync Guide - Using BuildKit Commands

Wiki Sync Guide - Using BuildKit Commands

Overview

Available BuildKit Wiki Sync Commands

1. Basic Wiki Management

Create Wiki Page

Edit Existing Wiki Page

List All Wiki Pages

Search Wiki Pages

2. Migrate Markdown Files to Wiki

Bulk Migration (Recommended)

3. Sync Between Repositories

Sync Wiki Pages Only

Sync All Repository Data (Issues, Milestones, Wiki)

4. Continuous Documentation Sync

Configuration

Project ID Resolution

Sync Configuration File

Common Workflows

Workflow 1: Migrate All Project Docs to Wiki

Workflow 2: Keep Two Wiki Repos in Sync

Workflow 3: Update Documentation in Primary, Sync to Secondary

Workflow 4: Continuous Sync to Technical Bible

Error Handling

Common Errors and Solutions

Error: "Project not found"

Error: "Page already exists"

Error: "Sync conflict detected"

Best Practices

1. Always Use Dry-Run First

2. Verify Permissions

3. Use GitLab Wiki as Single Source of Truth

4. Configuration Management

5. Monitoring and Logging

6. Content Organization

Advanced Features

Metadata Preservation

Conflict Resolution

Search Functionality

Troubleshooting

Wiki Pages Not Syncing

Metadata Lost During Sync

Slow Sync Performance

Related Commands

See Also

Support