feat: support settings.xml to be passed as file-type variable

README.md

@@ -17,23 +17,30 @@ include:
 
 The Maven template uses some global configuration throughout all jobs.
 
-| Name                  | description                            | default value     |
-| --------------------- | -------------------------------------- | ----------------- |
-| `MAVEN_IMAGE`         | The Docker image used to run Maven <br/>:warning: **set the version required by your project** | `registry.hub.docker.com/library/maven:latest` |
-| `MAVEN_PROJECT_DIR`   | Maven projet root directory | `.` |
-| `MAVEN_CFG_DIR`       | The Maven configuration directory      | `.m2`             |
-| `MAVEN_OPTS`          | [Global Maven options](http://maven.apache.org/configure.html#maven_opts-environment-variable) | `-Dhttps.protocols=TLSv1.2 -Dmaven.repo.local=${MAVEN_CFG_DIR}/repository -Dorg.slf4j.simpleLogger.showDateTime=true -Djava.awt.headless=true` |
-| `MAVEN_CLI_OPTS`      | Additional [Maven options](https://maven.apache.org/ref/3-LATEST/maven-embedder/cli.html) used on the command line | `--no-transfer-progress --batch-mode --errors --fail-at-end --show-version -DinstallAtEnd=true -DdeployAtEnd=true` |
+| Name                  | description                                                                                                        | default value                                                                                                                                  |
+| --------------------- |--------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| `MAVEN_IMAGE`         | The Docker image used to run Maven <br/>:warning: **set the version required by your project**                     | `registry.hub.docker.com/library/maven:latest`                                                                                                 |
+| `MAVEN_PROJECT_DIR`   | Maven projet root directory                                                                                        | `.`                                                                                                                                            |
+| `MAVEN_CFG_DIR`       | The Maven configuration directory                                                                                  | `.m2`                                                                                                                                          |
+| `MAVEN_SETTINGS_FILE`       | The Maven `settings.xml` file path                                                                        | `${MAVEN_CFG_DIR}/settings.xml`                                                                                                                |
+| `MAVEN_OPTS`          | [Global Maven options](http://maven.apache.org/configure.html#maven_opts-environment-variable)                     | `-Dhttps.protocols=TLSv1.2 -Dmaven.repo.local=${MAVEN_CFG_DIR}/repository -Dorg.slf4j.simpleLogger.showDateTime=true -Djava.awt.headless=true` |
+| `MAVEN_CLI_OPTS`      | Additional [Maven options](https://maven.apache.org/ref/3-LATEST/maven-embedder/cli.html) used on the command line | `--no-transfer-progress --batch-mode --errors --fail-at-end --show-version -DinstallAtEnd=true -DdeployAtEnd=true`                             |
 
 ### About `$MAVEN_CFG_DIR`
 
-This variable is used to define the Maven configuration directory. It is used for two (2) purposes:
-
-* in case a Maven settings file (`settings.xml`) is found, the template automatically uses it (using the `-s` option on command line),
-* the cache policy declares the `${MAVEN_CFG_DIR}/repository` directory as cached (not to download Maven dependencies over and over again).
+This variable is used to define the Maven configuration directory. It is used to declare the cache policy and marked the `${MAVEN_CFG_DIR}/repository` directory as cached (not to download Maven dependencies over and over again).
 
 If you have a good reason to do differently, you'll have to override the `MAVEN_CLI_OPTS` variable as well as the [`cache`](https://docs.gitlab.com/ee/ci/yaml/README.html#cache) policy.
 
+### About `$MAVEN_SETTINGS_FILE`
+
+If a file is found at the `$MAVEN_SETTINGS_FILE` location, the template automatically uses it as a `settings.xml` (using the [`--settings` option](https://maven.apache.org/ref/current/maven-embedder/cli.html) on command line).
+
+Note that with this design you are free to either:
+
+1. inline the `settings.xml` file into your repository source (:warning: make sure not to inline secrets but use the `${env.MY_PASSWORD}` replacement pattern instead and define the `MY_PASSWORD` variable as secret project variable),
+2. or define the `settings.xml` content as a [file type project variable](https://docs.gitlab.com/ee/ci/variables/#use-file-type-cicd-variables).
+
 ## Jobs
 
 ### `mvn-build` job
@@ -236,7 +243,7 @@ You may handle them in the following ways:
 <!-- ... -->
 ```
 
-`${MAVEN_CFG_DIR}/settings.xml`:
+`${MAVEN_SETTINGS_FILE}`:
 
 ```xml
 <settings>

kicker.json

@@ -21,6 +21,12 @@
       "default": ".m2",
       "advanced": true
     },
+    {
+      "name": "MAVEN_SETTINGS_FILE",
+      "description": "The Maven `settings.xml` file path",
+      "default": "${MAVEN_CFG_DIR}/settings.xml",
+      "advanced": true
+    },
     {
       "name": "MAVEN_OPTS",
       "description": "[Global Maven options](http://maven.apache.org/configure.html#maven_opts-environment-variable)",

templates/gitlab-ci-maven.yml

@@ -57,6 +57,8 @@ variables:
 
   # default configuration directory
   MAVEN_CFG_DIR: ".m2"
+  # default settings.xml file path
+  MAVEN_SETTINGS_FILE: "$MAVEN_CFG_DIR/settings.xml"
 
   # `showDateTime` will show the passed time in milliseconds. You need to specify `--batch-mode` to make this work.
   MAVEN_OPTS: >-
@@ -344,12 +346,12 @@ stages:
     fi
   }
 
-  # autodetects any Maven settings file in $MAVEN_CFG_DIR and builds the Java CLI option accordingly
+  # autodetects any Maven settings file in and builds the Java CLI option accordingly
   function eval_mvn_settings_opt() {
-    if [[ -f "$MAVEN_CFG_DIR/settings.xml" ]]
+    if [[ -f "$MAVEN_SETTINGS_FILE" ]]
     then
-      log_info "Maven settings file found: \\e[33;1m$MAVEN_CFG_DIR/settings.xml\\e[0m"
-      mvn_settings_opt="-s $MAVEN_CFG_DIR/settings.xml"
+      log_info "Maven settings file found: \\e[33;1m$MAVEN_SETTINGS_FILE\\e[0m"
+      mvn_settings_opt="-s $MAVEN_SETTINGS_FILE"
     fi
   }