Kimura SCM

Appearance

CI/CD with KSCM ​

Overview ​

The KSCM CLI makes it straightforward to automate build and validation pipelines by creating workspaces on demand, keeping long-lived workspaces for incremental builds, and syncing to the latest revisions. It also supports workspace stashes that can be retrieved, tested, and updated as part of your CI process. Attachments let you publish CI artifacts, summaries, and reviews directly on repo changelists, workspace changelists, and stashes. Secondary file servers can be used as local caches near your build agents to speed up syncs and reduce WAN traffic, and LLM-assisted workflows can generate and attach documentation automatically.

This document describes common CI/CD patterns and how to express them with KSCM commands, including attachments and LLM automation.

Building blocks ​

Use these commands as the foundation for automation:

  • create-workspace / delete-workspace for ephemeral build agents.

  • create-workspace for long-lived, incremental build sessions (reuse the same workspace across jobs).

  • sync to bring a workspace to the latest revision.

  • history, show-revision, list-changelists, show-changelist to inspect changes and determine which tasks to run.

  • stash-changelist, list-stashes (for example with --tags), show-stash, retrieve-stash, edit-stash to find stashes to test (for example, stashes tagged with a build machine name), retrieve them, run validation, then update the stash metadata with the results.

  • list-attachments, upload-attachment, download-attachment, delete-attachment to publish CI artifacts, summaries, or reviews directly on repo changelists, workspace changelists, and stashes.

  • clean-workspace to reset a workspace to a pristine state when needed.

Pattern: ephemeral workspaces ​

For clean builds, create a workspace, sync to the latest revision, run the pipeline, then delete the workspace.

text
# Create a workspace for a build agent
kscm create-workspace --name:CI-Agent-01 --path:/build/agent01 --repomap:Main

# Sync to the latest revision
kscm sync --workspace:CI-Agent-01

# Run build/test steps...

# Delete the workspace when the job is done
kscm delete-workspace --workspace:CI-Agent-01

Pattern: long-lived workspaces for incremental builds ​

Incremental builds are more efficient when the workspace is kept alive across jobs. Create the workspace once, then reuse it for rapid syncs and repeated operations.

text
# Create a long-lived workspace for a build agent (done once)
kscm create-workspace --name:CI-Agent-LongLived --path:/build/agent-longlived --repomap:Main

# In subsequent jobs, sync and build against the long-lived workspace
kscm sync --workspace:CI-Agent-LongLived

This pattern is ideal for continuous integration systems that run frequently and benefit from preserving intermediate build artifacts.

Detecting tasks through changelist tags ​

Pipelines often need to decide which jobs to run based on metadata in a changelist. If your workflow uses tags in changelist descriptions or metadata, query the changelist and route tasks accordingly.

Example approach:

  1. Use list-changelists (optionally with --tags) to identify relevant changelists.
  2. Use show-changelist to read descriptions or tag metadata.
  3. Map tags to pipeline tasks (e.g., build, tests, package).
text
kscm list-changelists --workspace:CI-Agent-LongLived --tags:build,tests
kscm show-changelist --workspace:CI-Agent-LongLived --clid:123

Validating stashed changelists ​

Stashes are useful for CI validation before submitting changes. A common flow is:

  • Create or update a stash for a changelist.
  • Load the stash into a validation workspace.
  • Run validation tasks.
  • Clean the workspace after validation.
text
# Find stashes to validate (for example, tagged for a specific build machine)
kscm list-stashes --workspace:CI-Validation --scope:remote --tags:ci-agent-01

# Retrieve a stash into a validation workspace
kscm retrieve-stash --id:1030 --workspace:CI-Validation --boundcl:new --conflicts:backup

# Run validation tasks...

# Clean workspace after validation
kscm clean-workspace --workspace:CI-Validation

Attachments for CI artifacts ​

Attachments are a simple way to share build artifacts (logs, reports, binaries, screenshots, and more) directly on repo changelists, workspace changelists, and stashes. They are ideal for CI pipelines that want to keep outputs close to the code review context.

There are no limitations on attachment sizes, so pipelines can publish large artifacts when needed.

Note: This is a good fit for Unreal Engine precompiled binaries, which are often large but useful for downstream teams.

Using LLMs to generate docs, summaries, and reviews ​

Kimura SCM's skill pack gives an LLM the context it needs to turn a natural-language request into safe, concrete kscm commands. The LLM performs the reasoning and document generation; KSCM performs the workspace inspection and SCM operations.

The resulting summaries, reviews, and risk notes can be attached to repo changelists, workspace changelists, or stashes so that the analysis stays with the work it describes.

Default skills ​

The default skill pack includes:

  • kscm-cli: maps task requests to valid KSCM commands, options, and workflows.
  • kscm-cl-compare: compares two KSCM artifacts and generates a summary, review, risk note, or requested custom document. It can also attach the result when requested.

These skills are intentionally basic. Teams can customize them, combine them with other skills, or create project-specific variants.

Ways to access the skills ​

The same default skill pack is available through several access paths:

  • Installed files: the Windows installer places each SKILL.md under skills/<skill-name>/ in the Kimura SCM installation directory. The macOS installer places them under /Library/Application Support/KimuraSCM/skills/<skill-name>/, and the Ubuntu package places them under /usr/share/kimurascm/skills/<skill-name>/. Assistant tools can load those files directly.

  • Embedded CLI resources: each kscm executable embeds the default skill files. Use the following command to export them:

    text
    kscm export-skills --destination:./.codex/skills

    The command always exports the complete skill pack embedded in the current KSCM executable and replaces existing skill files with that version.

  • MCP: when kscm runs in MCP mode, export-skills is available as an MCP tool. This lets an MCP client materialize the embedded pack without shelling out to a separate CLI process.

  • Repository source: developers can read and customize the source files under .codex/skills/ before packaging or exporting them.

Choosing a workflow ​

Use the regular CLI for one-shot commands and CI steps that already have a shell environment. Use kscm mcp when an assistant or automation host will make several related calls and benefit from a persistent KSCM process.

The kscm-cl-compare workflow accepts two supported sources, such as:

  • a submitted repo changelist from show-revision;
  • a workspace changelist from show-workspace-cl --ops:true;
  • a stash or stash revision from show-stash.

The LLM should identify both sources, collect their operation or revision details, generate the requested document, and confirm the attachment target before uploading unless the workflow already specifies it.

Example workflows ​

Review a submitted repo changelist and attach the review to that repo changelist:

text
kscm show-revision --clid:1756 --workspace:CI-Agent
# generate the review from the inspected changelist
kscm upload-attachment --target:repo --clid:1756 --file:cl-1756-review.md --workspace:CI-Agent

Review a remote stash selected by a tag, attach the result, and mark it reviewed:

text
kscm list-stashes --workspace:CI-Validation --scope:remote --tags:nr
kscm show-stash --id:<stash-id> --scope:remote --workspace:CI-Validation
# generate the review
kscm upload-attachment --target:stash --id:<stash-id> --stash-scope:remote --file:stash-<stash-id>-review.md --workspace:CI-Validation
kscm edit-stash --id:<stash-id> --description:"... #reviewed" --scope:remote --workspace:CI-Validation

Generate separate summary and risk documents for a workspace changelist:

text
kscm show-workspace-cl --clid:1827 --ops:true --workspace:CI-Agent
# generate the summary and risk note
kscm upload-attachment --target:workspace-cl --clid:1827 --file:cl-1827-summary.md --workspace:CI-Agent
kscm upload-attachment --target:workspace-cl --clid:1827 --file:cl-1827-risk.md --workspace:CI-Agent

CI-friendly workflow pattern ​

A repeatable CI workflow is:

  1. Find work items that need analysis, often by filtering stash or changelist tags.
  2. Inspect the selected artifact and collect the relevant operations or revision data.
  3. Generate the requested summary, review, risk note, or custom document.
  4. Write the document to a known local path.
  5. Upload it with the correct attachment target and scope.
  6. Update a tag, such as #nr to #reviewed, so the same item is not processed repeatedly.

For unattended jobs, keep the source selector, attachment target, output filename, and tag transition explicit. Do not infer a remote stash scope or upload target when more than one interpretation is possible.

Cleaning and resetting workspaces ​

CI pipelines often require clean state. Use clean-workspace to reset a workspace to a pristine state that matches the latest revision (or a specific revision with --clid).

text
kscm clean-workspace --workspace:CI-Agent-LongLived

Secondary file servers for faster syncs ​

To reduce network load, configure a secondary file server that is local to your CI environment. This allows workspaces to sync files from a nearby cache instead of repeatedly pulling large file sets over the WAN.

When creating a workspace, specify the secondary file server name and endpoint for the local cache server:

text
kscm create-workspace --name:CI-Agent-01 --path:/build/agent01 --repomap:Main \
  --secondaryfsname:FS-LOCAL --secondaryfsendpoint:localhost:9000

This is especially useful for build farms or distributed CI setups where many agents pull the same content repeatedly.

Summary ​

The KSCM CLI supports CI/CD workflows that range from clean, ephemeral builds to long-lived, incremental pipelines. By combining workspace hosting, fast syncs, changelist-driven routing, stash validation, and secondary file servers, you can build efficient automation that scales with your build infrastructure.