Skip to content

Consumer Sync Guide

This guide covers syncing BaseCoat assets into a consumer repository and keeping them up to date.

What gets synced

The sync script copies all distributable assets to .github/base-coat/ in your repo:

  • agents/ — all agent definition files
  • skills/ — all skill directories
  • instructions/ — all instruction files
  • prompts/ — prompt templates
  • version.json — version metadata

Files that are not synced: basecoat-metadata.json (internal portal index), test scripts, CI workflows, and internal tooling. Selected documentation content is synced under .github/base-coat/docs/, but not the full source docs/ tree.

Sync commands

# Sync latest release (from main)
$env:BASECOAT_REPO = 'https://github.com/ivegamsft/basecoat.git'
.\sync.ps1

# Sync a specific version tag
$env:BASECOAT_REPO = 'https://github.com/ivegamsft/basecoat.git'
$env:BASECOAT_REF  = 'v3.25.0'
.\sync.ps1

# Sync to a custom target directory
$env:BASECOAT_REPO       = 'https://github.com/ivegamsft/basecoat.git'
$env:BASECOAT_TARGET_DIR = '.github/my-basecoat'
.\sync.ps1

# Sync latest release (from main)
BASECOAT_REPO=https://github.com/ivegamsft/basecoat.git ./sync.sh

# Sync a specific version tag
BASECOAT_REPO=https://github.com/ivegamsft/basecoat.git \
BASECOAT_REF=v3.25.0 ./sync.sh

# Sync to a custom target directory
BASECOAT_REPO=https://github.com/ivegamsft/basecoat.git \
BASECOAT_TARGET_DIR=.github/my-basecoat ./sync.sh

Scoped sync patterns

For consumers that only need part of BaseCoat, use .basecoat.yml allow-lists instead of syncing the full catalog.

# .basecoat.yml
source: https://github.com/ivegamsft/basecoat.git
ref: v3.25.0

agents:
  - code-review
  - security-review

skills:
  - harden
  - azure-diagnostics

instructions:
  - governance
  - security-baseline

sync:
  exclude:
    - archive/

This keeps updates scoped and auditable because every synced category is declared in source control. For full key reference and more examples, see BaseCoat Config (.basecoat.yml).

Quick refresh shortcut

In Copilot-enabled environments, use the phrase refresh basecoat to trigger the rollout workflow.

If your environment reports Skill not found: rollout-basecoat, run sync directly from the consumer repo root:

$env:BASECOAT_REPO = 'https://github.com/ivegamsft/basecoat.git'
$env:BASECOAT_REF  = 'main'  # or vX.Y.Z
.\sync.ps1

BASECOAT_REPO=https://github.com/ivegamsft/basecoat.git \
BASECOAT_REF=main ./sync.sh

Checking your version

cat .github/base-coat/version.json

Auditability: capture a sync trail

Record before/after evidence in each consumer upgrade PR so overrides and drift are reviewable.

# 1) Record current synced version
Get-Content .github/base-coat/version.json

# 2) Run scoped sync (uses .basecoat.yml allow-lists when present)
$env:BASECOAT_REPO = 'https://github.com/ivegamsft/basecoat.git'
.\sync.ps1

# 3) Save an auditable patch for reviewer traceability
New-Item -ItemType Directory -Force -Path .github\base-coat-audit | Out-Null
git --no-pager diff -- .github/base-coat |
  Set-Content ".github\base-coat-audit\sync-$((Get-Date).ToString('yyyy-MM-dd')).diff"
git --no-pager diff --stat -- .github/base-coat

# 1) Record current synced version
cat .github/base-coat/version.json

# 2) Run scoped sync (uses .basecoat.yml allow-lists when present)
BASECOAT_REPO=https://github.com/ivegamsft/basecoat.git ./sync.sh

# 3) Save an auditable patch for reviewer traceability
mkdir -p .github/base-coat-audit
git --no-pager diff -- .github/base-coat > ".github/base-coat-audit/sync-$(date +%F).diff"
git --no-pager diff --stat -- .github/base-coat

Automating upgrades

Add the callable drift-detection workflow to get automatic issue notifications when a new BaseCoat version is available. See Getting Started.

Naming convention

BaseCoat uses two names intentionally:

Name Used for
basecoat GitHub repo, internal scripts, environment variables (BASECOAT_*)
base-coat Distributed artifact, sync target (.github/base-coat/), version.json, release archives

See ADR-001 for full details.

See also