README

This plugin uses template files to automatically generate various project configuration files and documentation.

ngss-filegen-maven-plugin 6.0+ includes new Copier-based goals for managing DevOps and Backstage configurations using template-driven workflows. See the Copier Goals Guide for details.

Template Management: Traditional vs. Copier-Based Workflows

Starting with version 6.0, the plugin offers a new approach for managing configuration files:

Traditional Static Template Workflow (Pre-6.0)

The traditional approach uses static templates stored in the ckm-deployment-templates BitBucket repository:

How it works:

Plugin downloads template files from BitBucket on demand
Performs variable substitution using Maven properties and metadata files
Generates files directly into your project
Files are regenerated completely on each execution

Characteristics:

✅ Simple one-command generation
✅ Good for files that rarely change
❌ No built-in update mechanism
❌ Manual merging required when templates change
❌ Difficult to track what changed between template versions
❌ Local customizations can be overwritten
❌ No clear separation between template changes and local modifications

New Copier-Based Workflow (6.0+)

The new copier-based approach uses Copier, a project templating tool:

How it works:

Initialization: Run an init goal (e.g., copier-devops-init) to copy files from a Git template repository
Interactive Setup: Answer configuration questions interactively
Answers Storage: Your responses are saved in .copier-answers/*.yaml files
Smart Updates: Run an update goal (e.g., copier-devops-update) to merge new template changes
Conflict Resolution: Copier intelligently merges updates while preserving your modifications

Key Technical Features:

Git-based templates: Templates are versioned Git repositories with full history
Answer persistence: Configuration choices are tracked in YAML files
Three-way merge: Updates use Git-style merging (template base → your version → new template)
Selective updates: Only modified template files are updated
Version pinning: Can specify exact template versions (tags/commits)
Change tracking: Clear diff between template updates and local changes

Advantages over Traditional Approach:

Aspect	Traditional (Pre-6.0)	Copier-Based (6.0+)
Template Updates	Manual - must regenerate and merge conflicts yourself	Automated - intelligent three-way merge preserves local changes
Version Control	No tracking of template version used	Explicit version tracking in answers file
Local Customizations	Risk of being overwritten on regeneration	Protected - Copier preserves your modifications
Update Visibility	Unclear what changed in template vs. local modifications	Clear separation - see exactly what template changed
Template Evolution	Difficult to adopt new template features incrementally	Easy incremental adoption of new template versions
Configuration Drift	Projects drift as templates evolve	Stay synchronized with upstream templates
Rollback	Difficult to revert to previous template version	Easy - just specify previous template version/tag

Aspect

Traditional (Pre-6.0)

Copier-Based (6.0+)

Template Updates

Manual - must regenerate and merge conflicts yourself

Automated - intelligent three-way merge preserves local changes

Version Control

No tracking of template version used

Explicit version tracking in answers file

Local Customizations

Risk of being overwritten on regeneration

Protected - Copier preserves your modifications

Update Visibility

Unclear what changed in template vs. local modifications

Clear separation - see exactly what template changed

Template Evolution

Difficult to adopt new template features incrementally

Easy incremental adoption of new template versions

Configuration Drift

Projects drift as templates evolve

Stay synchronized with upstream templates

Rollback

Difficult to revert to previous template version

Easy - just specify previous template version/tag

Real-World Example:

# Initial setup (one time)
mvn filegen:copier-devops-init
# Answer questions interactively...
# Files generated, .copier-answers/devops.yaml created

# Six months later, template has new features
mvn filegen:copier-devops-update
# Copier shows you what changed in template
# Prompts only for NEW questions
# Intelligently merges updates with your customizations
# Your local modifications are preserved!

# Or update to specific version
mvn filegen:copier-devops-update -Dcopier.devops.version=v2.0.0

Use Copier Goals (copier-*) for:

DevOps and Backstage configurations that evolve over time
Projects that need to stay synchronized with template improvements
Teams that want consistent configuration across projects
Scenarios where template updates need to merge with local customizations
Long-lived projects that will receive template updates

The copier-based workflow is particularly valuable for DevOps and Backstage configurations because these tend to evolve significantly as new features, best practices, and requirements emerge. For this "tech preview", the other goals will remain as-is but may be replaced with Copier-based implementations in a future update.

Plugin Setup

The following steps must be done one time in order to set up the plugin to work on all projects.

Add BitBucket Token to Maven Settings

To use the generator, you must have an account for the VA BitBucket - coderepo.mobilehealth.va.gov

Add your account credentials to the ~/.m2/settings.xml file so that it can be used during Maven builds:

    <server>
      <id>bitbucket</id>
      <username>YourUserName</username>
      <password>YourPassword or Token</password>
    </server>

NOTE: As of Release 3.0 you can use either a plain text password, or a maven encrypted password: mvn --encrypt-password <password>

Project Setup

filegen uses some metadata.yaml documentation fields for populating variables in various templates. Here is how each field is used.

documentation:
  jiraProjectKey: ckm    # (required) vv.yaml
  po: John Doe           # (optional) vv.yaml
  apigw:                 # (optional) dibr.md
    registration: both
  vault:                 # (optional) dibr.md
  - name: SECRET_PWD
    comment: The password to authenticate with.

Generate CI Files

Here are the commands to generate the corresponding files. Each "Maven Goal" is executed by running it using the standard Maven plugin syntax, mvn filegen:<goal>

Maven Goal File(s) Generated Property Source(s)

Maven Goal	File(s) Generated	Property Source(s)
`generate-dibr-readme`	`dibr.md`	`templates/dibr/dibr.properties`, `kubernetes/base/service.yaml`
`generate-flyway-scripts`	wait_for_postgres.sh wait_for_oracle.sh flyway_migrate.sh sql/README.md init/db-user-and-schema.sql	`templates/dibr/dibr.properties`, `kubernetes/base/service.yaml`
`generate-jenkinsfile` (see note below)	`Jenkinsfile`	N/A
`jenkins-yaml`	`jenkins.yaml`	`metadata.yaml`, `vv.yaml`, `pom.xml`
`copier-devops-init`	DevOps configuration files	Git-based template (see Copier Goals)
`copier-devops-update`	Updated DevOps configuration files	Git-based template, `.copier-answers/devops.yaml`
`copier-backstage-init`	Backstage configuration files	Git-based template (see Copier Goals)
`copier-backstage-update`	Updated Backstage configuration files	Git-based template, `.copier-answers/backstage.yaml`

generate-dibr-readme

dibr.md

templates/dibr/dibr.properties, kubernetes/base/service.yaml

generate-flyway-scripts

  wait_for_postgres.sh
  wait_for_oracle.sh
  flyway_migrate.sh
  sql/README.md
  init/db-user-and-schema.sql

templates/dibr/dibr.properties, kubernetes/base/service.yaml

generate-jenkinsfile (see note below)

Jenkinsfile

N/A

jenkins-yaml

jenkins.yaml

metadata.yaml, vv.yaml, pom.xml

copier-devops-init

DevOps configuration files

Git-based template (see Copier Goals)

copier-devops-update

Updated DevOps configuration files

Git-based template, .copier-answers/devops.yaml

copier-backstage-init

Backstage configuration files

Git-based template (see Copier Goals)

copier-backstage-update

Updated Backstage configuration files

Git-based template, .copier-answers/backstage.yaml

For detailed information about the Copier-based goals, including all available options and workflow examples, see the Copier Goals Guide.

During the tech preview (6.0) period, the Jenkinsfile is also included in the DevOps templates during generation and update. This may change in the future so that the Jenkinsfile can be managed without Skaffold and Kustomize files.

Maven Plugin Tiles

To provide an easy method of configuration, the NGSS Maven Tiles project defines several Maven Tile configurations (pom.xml snippets) which can be included in your project pom.xml. The examples in the following sections assume that the ngss-maven-tiles.version property is set in the pom.xml <properties> tag and that the tiles-maven-plugin is configured in the <plugins> tag.

<plugin>
    <groupId>io.repaint.maven</groupId>
    <artifactId>tiles-maven-plugin</artifactId>
    <extensions>true</extensions>
    <configuration>
        <tiles>
            <!-- include tiles -->
        </tiles>
    </configuration>
</plugin>

filegen-tile

<tile>gov.va.mobile.tools.maven:filegen-tile:${ngss-maven-tiles.version}</tile>

Base ngss-filegen-maven-plugin configuration, which allows you to run any of its defined Maven goals directly

vv-automation-tile

<tile>gov.va.mobile.tools.maven:vv-automation-tile:${ngss-maven-tiles.version}</tile>

Generates the vv.yaml on each build
Bound to the process-resources phase, so any higher phase (like mvn package, mvn install, etc.) will trigger its execution

dibr-readme-generator-tile

<tile>gov.va.mobile.tools.maven:dibr-readme-generator-tile:${ngss-maven-tiles.version}</tile>

Generates the dibr.md on each build
Bound to the package phase