Template Versioning

This guide covers how to select, check, and update template versions.

Default Behavior

By default, Copier selects the latest release tag following semantic versioning (e.g., v1.2.3). Pre-release versions (e.g., v2.0.0-RC1) are not selected unless explicitly requested.

Selecting a Specific Version

Use --vcs-ref to specify a version when copying or updating:

# Use a specific release version
copier copy https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git . --vcs-ref=v1.2.0

# Use a pre-release version (e.g., release candidate)
copier copy https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git . --vcs-ref=v2.0.0-RC1

# Use a branch (for testing unreleased changes)
copier copy https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git . --vcs-ref=feature-branch

# Use a specific commit
copier copy https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git . --vcs-ref=abc123def

# Update to a specific version
copier update -a .copier-answers/devops.yaml --vcs-ref=v1.3.0

Maven equivalent:

# Initialize with specific version
mvn filegen:copier-init -Dcopier.template=devops -Dcopier.version=v2.0.0-RC1

# Update to specific version
mvn filegen:copier-update -Dcopier.template=devops -Dcopier.version=v1.3.0

# Update multiple templates with different versions
mvn filegen:copier-update -Dcopier.updateTemplates=devops,backstage \
  -Dcopier.devops.version=v3.5.0 \
  -Dcopier.backstage.version=v2.1.0

Listing Available Versions

To see all available template versions:

git ls-remote --tags https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git
git ls-remote --tags https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-backstage-template.git

Checking for Updates

Use copier check-update to see if a newer template version is available without applying changes:

# Check if updates are available (stable releases only)
copier check-update -a .copier-answers/devops.yaml .

# Include pre-release versions (RC, alpha, beta) in the check
copier check-update -a .copier-answers/devops.yaml . --prereleases

# Check a specific template
copier check-update -a .copier-answers/backstage.yaml .

The command outputs:

  • Current template version you’re using

  • Latest available version

  • Exit code 0 if up-to-date, non-zero if updates available

Testing Pre-Release Versions

To test release candidates (RC) or pre-release versions of templates, tiles, or filegen plugin, you must explicitly opt-in using the --prereleases flag.

Why Pre-Releases Aren’t Default

Pre-release versions (e.g., v2.0.0-RC1, v1.5.0-beta1) are excluded by default to ensure production stability. Only explicitly tagged stable releases are used unless you opt-in.

Using Pre-Releases with Copier CLI

# Check for pre-release updates
copier check-update -a .copier-answers/devops.yaml . --prereleases

# Update to latest including pre-releases
copier update -a .copier-answers/devops.yaml --prereleases

# Initialize with pre-release version
copier copy https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git . --prereleases

Using Pre-Releases with Maven Goals

# Command line
mvn filegen:copier-init -Dcopier.template=devops -Dcopier.prereleases
mvn filegen:copier-update -Dcopier.prereleases

# Or pin to a specific pre-release version
mvn filegen:copier-init -Dcopier.template=devops -Dcopier.devops.version=v2.0.0-RC1

Or set in pom.xml properties:

<properties>
    <copier.prereleases>true</copier.prereleases>
    <!-- Or pin specific template versions -->
    <copier.devops.version>v2.0.0-RC1</copier.devops.version>
    <copier.backstage.version>v1.5.0-beta1</copier.backstage.version>
</properties>
When testing RC versions, provide feedback to the template maintainers before stable release.

Update Behavior Options

When running copier update, you can control how prompts are handled:

# Skip questions already answered, prompt for new questions only
copier update -a .copier-answers/devops.yaml --skip-answered

# Use defaults for all questions (fully non-interactive)
copier update -a .copier-answers/devops.yaml --defaults

# Re-prompt for specific questions
copier update -a .copier-answers/devops.yaml --ask vaec_vasi --ask version
Flag Behavior

--skip-answered (or -A)

Skips questions with existing answers; prompts for new questions added in newer template versions

--defaults (or -d)

Uses default values for all questions without prompting (fully non-interactive)

--ask <question>

Forces re-prompting for a specific question even if already answered

Answers File Version Tracking

The .copier-answers/*.yaml files track which template version was used:

_commit: abc123def456...
_src_path: https://coderepo.mobilehealth.va.gov/scm/ckm/ngss-devops-template.git
Never edit the Copier answers files directly as these are managed by Copier itself. See Copier documentation.

This enables:

  • Reproducing the exact configuration at any point

  • Knowing when updates are available

  • Rolling back if a new version causes issues