Copier Maven Goals

This guide covers the copier-based Maven goals for managing configuration files from templates using the Copier CLI tool.

Quick Reference

Goal Usage Description

copier-init

mvn filegen:copier-init -Dcopier.template=<name>

Initialize files from any template

copier-update

mvn filegen:copier-update -Dcopier.template=<name>

Update files from any template

Overview

The NGSS Filegen Maven Plugin includes support for Copier, a tool for rendering project templates. Copier allows you to initialize and update configuration files from Git-based templates while preserving your local modifications.

The plugin provides generic goals that work with any template, including DevOps, Backstage, and custom templates.

Prerequisites

Install Copier

Before using the copier goals, you must have Copier and its dependencies installed on your system:

brew install python # if needed
brew install pipx
pipx install copier
pipx inject copier copier-template-extensions
pipx ensurepath

Verify the installation:

copier --version

For more information, see the Copier documentation.

Template Repositories

The plugin supports template repositories including:

Available Goals

copier-init

Initialize configuration files from any template.

mvn filegen:copier-init -Dcopier.template=devops
mvn filegen:copier-init -Dcopier.template=backstage
mvn filegen:copier-init -Dcopier.template=spring-mcp

This goal:

  • Runs Copier in "copy" mode to initialize files

  • Prompts you interactively for configuration values

  • Generates a .copier-answers/<template>.yaml file with your responses

  • Creates the configuration files in your project

Properties:

Property Default Description

copier.template

(required)

Template name (devops, backstage, or spring-mcp)

copier.skip

false

Skip execution of the goal

copier.templateUrl

(auto-resolved)

Custom template Git URL (overrides default)

copier.destination

.

Destination directory

copier.trust

true

Whether to trust the template

copier.version

(latest)

Template version/tag to use

Example with custom template:

mvn filegen:copier-init \
  -Dcopier.template=custom \
  -Dcopier.templateUrl=https://example.com/my-template.git

Example with specific version:

mvn filegen:copier-init \
  -Dcopier.template=devops \
  -Dcopier.version=v2.0.0

copier-update

Update configuration files from any template.

mvn filegen:copier-update -Dcopier.template=devops
mvn filegen:copier-update -Dcopier.template=backstage
mvn filegen:copier-update -Dcopier.template=spring-mcp

This goal:

  • Runs Copier in "update" mode to refresh files

  • Uses answers from .copier-answers/<template>.yaml

  • Prompts only for new or changed questions (with --skip-answered)

  • Preserves your local modifications

Properties:

Property Default Description

copier.template

(required for single template)

Template name (devops, backstage, or spring-mcp)

copier.updateTemplates

(optional)

List of templates to update (e.g., devops,backstage)

copier.skip

false

Skip execution of the goal

copier.answersFile

(auto-resolved)

Custom answers file path

copier.destination

.

Destination directory

copier.trust

true

Whether to trust the template

copier.skipAnswered

true

Skip previously-answered prompts

copier.version

(latest)

Template version/tag to use

copier.<template>.version

(optional)

Override version for specific template (e.g., copier.devops.version=v3.5.0)

Example with specific version:

mvn filegen:copier-update -Dcopier.template=devops -Dcopier.version=v2.1.0

Example updating multiple templates:

mvn filegen:copier-update -Dcopier.updateTemplates=devops,backstage

Example with auto-discovery of answers files in .copier-answers directory:

mvn filegen:copier-update

Example with per-template version overrides:

mvn filegen:copier-update -Dcopier.updateTemplates=devops,backstage \
  -Dcopier.devops.version=v3.5.0 \
  -Dcopier.backstage.version=v2.1.0

copier

Unified goal that supports both init and update modes.

Initialize:

mvn filegen:copier -Dcopier.init -Dcopier.template=devops

Update:

mvn filegen:copier -Dcopier.update -Dcopier.template=backstage

Properties:

Property Default Description

copier.init

false

Run in init mode (exactly one of init/update required)

copier.update

false

Run in update mode (exactly one of init/update required)

copier.template

(required)

Template name

copier.skip

false

Skip execution

copier.templateUrl

(auto-resolved)

Custom template URL

copier.destination

.

Destination directory

copier.trust

true

Trust the template

copier.version

(latest)

Template version

Workflow Examples

Initial Project Setup

When setting up a new project:

  1. Initialize DevOps configuration:

    mvn filegen:copier-init -Dcopier.template=devops

  2. Initialize Backstage configuration:

    mvn filegen:copier-init -Dcopier.template=backstage

  3. Commit the generated files and answers files:

    git add .copier-answers/
git commit -m "Initialize DevOps and Backstage configurations"

Updating to Latest Template Version

To update your project with the latest template changes:

  1. Update a single template:

    mvn filegen:copier-update -Dcopier.template=devops

  2. Or update all templates at once:

    mvn filegen:copier-update

    (This will update all templates that have answers files in .copier-answers/)

  3. Review changes and commit:

    git diff
git add -A
git commit -m "Update to latest template versions"

Updating to Specific Template Version

To update to a specific version of a template:

mvn filegen:copier-update -Dcopier.template=devops -Dcopier.version=v2.0.0

Or use per-template version overrides:

mvn filegen:copier-update -Dcopier.devops.version=v3.5.0

Updating Multiple Templates with Different Versions

To update multiple templates with specific versions:

mvn filegen:copier-update -Dcopier.updateTemplates=devops,backstage \
  -Dcopier.devops.version=v3.5.0 -Dcopier.backstage.version=v2.1.0

Using Custom Template Repository

To use a custom or forked template repository:

mvn filegen:copier-init -Dcopier.template=custom -Dcopier.templateUrl=https://example.com/my-custom-template.git

Answers Files

Copier stores your configuration answers in YAML files under .copier-answers/:

  • .copier-answers/devops.yaml - DevOps template answers

  • .copier-answers/backstage.yaml - Backstage template answers

These files should be committed to version control as they:

  • Record your configuration choices

  • Enable reproducible updates

  • Allow team members to update consistently

Skip Flags

All copier goals respect the following skip flags:

  • skipAll - Global skip flag for all filegen goals

  • copier.skip - Skip flag for copier goals

Example:

# Skip copier goal execution
mvn filegen:copier-init -Dcopier.template=devops -Dcopier.skip=true

# Skip all filegen goals
mvn install -DskipAll=true

Trust Flag

The trust flag controls whether Copier trusts the template to execute tasks and migrations. By default, this is set to true for convenience.

Only use templates from trusted sources. The --trust flag allows templates to execute arbitrary code.

To disable trust for security:

mvn filegen:copier-init -Dcopier.templateUrl=https://some-random-template.org/templates.git -Dcopier.trust=false

Troubleshooting

Copier Not Found

If you see an error about copier not being found:

  1. Verify Copier is installed:

    copier --version

  2. Ensure it’s in your PATH:

    which copier

  3. Install if missing:

    pipx install copier
pipx inject copier copier-template-extensions
pipx ensurepath

Answers File Not Found

If you see "Skipping…​ Answers file has not been initialized":

  1. Make sure you’ve run the init goal first:

    mvn filegen:copier-init -Dcopier.template=devops

  2. Verify the answers file exists:

    ls -la .copier-answers/

Template Version Issues

To check available template versions:

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

Best Practices

  1. Commit answers files: Always commit .copier-answers/ to version control

  2. Regular updates: Periodically update templates to get bug fixes and improvements

  3. Review changes: Always review template updates before committing

  4. Pin versions: Use specific versions in CI/CD for reproducibility

  5. Test updates: Test template updates in a feature branch first

See Also