Skip to content

Upgrading AcuOps Pipeline

This guide covers how to pull in new AcuOps releases when you've created your repo from the acuops-pipeline template.

How AcuOps Versioning Works

AcuOps uses semantic versioning (vMAJOR.MINOR.PATCH):

  • MAJOR — Breaking changes to config format, workflow inputs, or script interfaces
  • MINOR — New features, additional validation checks, intelligence improvements
  • PATCH — Bug fixes, documentation updates

Upgrade Methods

Best for repos with significant customization to AcuOps files.

# Add the upstream template as a remote (one-time setup)
git remote add acuops https://github.com/studio-b-ai/acuops-pipeline.git

# Fetch the latest
git fetch acuops

# View what changed between your version and the latest
git log acuops/main --oneline --since="2026-01-01"

# Cherry-pick specific commits you want
git cherry-pick <commit-sha>

Method 2: Merge Upstream (Clean Repos)

Best for repos that haven't modified AcuOps scripts or workflows.

# Add upstream remote
git remote add acuops https://github.com/studio-b-ai/acuops-pipeline.git

# Fetch and merge
git fetch acuops
git merge acuops/main --allow-unrelated-histories

# Resolve any conflicts (your acuops.yaml, project.xml will conflict — keep yours)
git checkout --ours acuops.yaml Customization/_project/project.xml
git add .
git commit

Method 3: Manual File Copy

For targeted updates — grab only the files you need.

# Download a specific file from the latest release
curl -sL https://raw.githubusercontent.com/studio-b-ai/acuops-pipeline/main/scripts/validate-project.py \
  -o scripts/validate-project.py

# Or download the full release archive and copy what you need

What to Update

File Update? Notes
scripts/*.py Yes Validator, intelligence, deploy client
scripts/*.sh Yes Deploy, backup, restore scripts
.github/workflows/acuops-deploy.yml Yes Pipeline workflow
.github/workflows/ci.yml Yes Self-testing CI
tests/ Yes Updated test fixtures and cases
acuops.yaml Merge Keep your values, adopt new keys
CLAUDE.md Merge Keep client-specific sections, update AcuOps sections
Customization/ No This is YOUR customization — never overwrite
data/deploy-history.json No This is YOUR deployment history

Pre-Upgrade Validation

Before upgrading, use the upgrade check workflow:

# Via GitHub Actions
# Go to Actions → AcuOps Upgrade Check → Run workflow
# Enter the target AcuOps version

# Locally
python scripts/validate-project.py --strict Customization/_project/project.xml
make check

Post-Upgrade Checklist

  1. Run make check — all tests and validations pass
  2. Check acuops.yaml — new config keys may have been added
  3. Review CHANGELOG.md — understand what changed
  4. Push to staging branch first — validate against staging environment
  5. Verify Deploy Intelligence history is intact (data/deploy-history.json)

Breaking Changes Log

v1.0 → v2.0 (Future)

No breaking changes yet — v1.0 is the first release.

When breaking changes occur, they will be documented here with migration steps.