maven-settings-xml-action

Maintained fork of whelk-io/maven-settings-xml-action with Node 24 runtime support.

The original repository by Zack Teater / whelk.io has been archived and is no longer maintained. The last upstream release (v22) uses the Node 20 runtime, which GitHub Actions is deprecating. This fork provides a drop-in replacement upgraded to Node 24.

What this Action does

This GitHub Action generates a custom Apache Maven settings.xml file during your CI/CD workflow. Instead of committing a settings.xml to your repository (which often contains sensitive credentials) or manually crafting it with shell commands, you declaratively define your Maven configuration as JSON inputs and the action produces a well-formed XML file at the path of your choosing (default: ~/.m2/settings.xml).

The action supports all major sections of the Maven settings specification:

Section	Description
`servers`	Authentication credentials for repositories and mirrors (username/password, private keys, custom configuration)
`mirrors`	Redirect repository requests to mirror URLs (e.g. Nexus, Artifactory)
`repositories`	Define custom artifact repositories with release/snapshot policies
`plugin_repositories`	Define custom plugin repositories with release/snapshot policies
`profiles`	Group repository, property, and plugin configuration under named profiles
`plugin_groups`	Short-circuit plugin resolution with custom group IDs
`active_profiles`	Activate specific profiles by ID regardless of environment
`proxies`	Route Maven HTTP traffic through proxy servers
`output_file`	Custom output path for the generated `settings.xml` (default: `~/.m2/settings.xml`)

How it works

The action loads a base settings.xml template
Your JSON inputs are parsed and transformed into XML DOM nodes
The nodes are appended to the appropriate sections of the template
The resulting XML is formatted and written to the specified output path

This means you get a clean, valid settings.xml every time without manual XML manipulation.

Migration from upstream

This is a drop-in replacement. No input changes, no behavior changes — only the runtime is updated.

# Before (Node 20 deprecation warning):
- uses: whelk-io/maven-settings-xml-action@v22

# After (Node 24, no warnings):
- uses: marcelrgberger/maven-settings-xml-action@v23

What changed in v23

Runtime: node20 → node24 in action.yml
Bundler: Replaced deprecated @zeit/ncc with @vercel/ncc
Engine constraint: engines.node updated from 16.x to >=20
CI: Build workflow uses Node 24 via actions/setup-node@v4
Tests: All 20 original tests passing without modification

Inputs

`servers`

Optional JSON array of servers to add to settings.xml.

Each server object supports:

id — The ID of the server that matches the id element of the repository/mirror Maven connects to.
username, password — Login credentials for authentication.
privateKey, passphrase — Path to a private key (default: ${user.home}/.ssh/id_dsa) and optional passphrase.
filePermissions, directoryPermissions — Three-digit *nix permissions for files/directories created on deployment (e.g. 664, 775).
configuration — Additional custom server configuration as nested JSON (converted to XML).

Reference: Maven Settings > Servers

`mirrors`

Optional JSON array of mirrors to add to settings.xml.

id — Unique identifier for this mirror. Used to match credentials from the <servers> section.
mirrorOf — The id of the repository this mirrors. Supports advanced patterns like repo1,repo2 or *,!inhouse.
url — Base URL of the mirror that replaces the original repository URL.

Reference: Maven Settings > Mirrors

`repositories`

Optional JSON array of repositories to add to settings.xml.

id — Repository ID (matches server id for authentication).
name — Human-readable repository name.
url — Repository URL.
releases.enabled — Enable/disable release artifacts ("true" / "false").
snapshots.enabled — Enable/disable snapshot artifacts ("true" / "false").

When repositories is empty or omitted, Maven Central is applied as the default:

repositories: |
  [
    {
      "id": "central",
      "name": "Maven Central",
      "url": "https://repo1.maven.org/maven2",
      "releases": { "enabled": "true" },
      "snapshots": { "enabled": "false" }
    }
  ]

Reference: Maven Settings > Repositories

`plugin_repositories`

Optional JSON array of plugin repositories to add to settings.xml.

Same structure as repositories, but for Maven plugin resolution.

Reference: Maven Settings > Plugin Repositories

`plugin_groups`

Optional JSON array of plugin group IDs to add to settings.xml.

Allows Maven to search additional group IDs when resolving plugins with incomplete coordinates.

Reference: Maven Settings > Plugin Groups

`profiles`

Optional JSON array of profiles to add to settings.xml.

The profile element in settings.xml is a truncated version of the POM profile. It supports activation, repositories, pluginRepositories, and properties — scoped to the build system rather than individual projects.

Reference: Maven Settings > Profiles

`active_profiles`

Optional JSON array of profile IDs to activate.

Any profile id listed here will be active regardless of environment settings. If no matching profile is found, execution continues normally.

Reference: Maven Settings > Active Profiles

`proxies`

Optional JSON array of proxies to add to settings.xml.

id — Unique identifier for this proxy.
active — "true" if this proxy is active.
protocol, host, port — Proxy connection details.
username, password — Proxy authentication credentials.
nonProxyHosts — Pipe-delimited (|) or comma-delimited list of hosts that bypass the proxy.

Reference: Maven Settings > Proxies

`output_file`

Optional Custom path for the generated settings.xml. Default: ~/.m2/settings.xml.

Supports environment variables (e.g. $GITHUB_WORKSPACE/custom.xml).

When using a custom path:

- uses: marcelrgberger/maven-settings-xml-action@v23
  with:
    output_file: foo/custom.xml

The file is created at /home/runner/work/{repo}/foo/custom.xml and can be referenced with mvn --settings foo/custom.xml {goal}.

Basic Usage

- name: Generate Maven settings.xml
  uses: marcelrgberger/maven-settings-xml-action@v23
  with:
    repositories: '[{ "id": "some-repository", "url": "http://some.repository.url" }]'
    plugin_repositories: '[{ "id": "some-plugin-repository", "url": "http://some.plugin.repository.url" }]'
    servers: '[{ "id": "some-server", "username": "some.user", "password": "some.password" }]'

Output:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">

    <activeProfiles>
        <activeProfile>github</activeProfile>
    </activeProfiles>

    <profiles>
        <profile>
            <id>github</id>
            <repositories>
                <repository>
                    <id>some-repository</id>
                    <url>http://some.repository.url</url>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>some-plugin-repository</id>
                    <url>http://some.plugin.repository.url</url>
                </pluginRepository>
            </pluginRepositories>
        </profile>
    </profiles>

    <servers>
        <server>
            <id>some-server</id>
            <username>some.user</username>
            <password>some.password</password>
        </server>
    </servers>

</settings>

Full Usage

- name: Generate Maven settings.xml
  uses: marcelrgberger/maven-settings-xml-action@v23
  with:
    repositories: >
      [
        {
          "id": "some-repository",
          "name": "some-repository-name",
          "url": "http://some.repository.url",
          "releases": {
            "enabled": "true",
            "updatePolicy": "always",
            "checksumPolicy": "fail"
          },
          "snapshots": {
            "enabled": "false",
            "updatePolicy": "always",
            "checksumPolicy": "fail"
          }
        }
      ]
    plugin_repositories: >
      [
        {
          "id": "some-plugin-repository",
          "name": "some-plugin-repository-name",
          "url": "http://some.plugin.repository.url",
          "releases": { "enabled": "true" },
          "snapshots": { "enabled": "false" }
        }
      ]
    servers: >
      [
        {
          "id": "some-id",
          "username": "${env.USER}",
          "password": "${env.PASS}",
          "configuration": {
            "httpConfiguration": {
              "all": {
                "usePreemptive": "true"
              }
            }
          }
        }
      ]
    mirrors: >
      [
        {
          "id": "nexus",
          "mirrorOf": "!my-org-snapshots,*",
          "url": "http://redacted/nexus/content/groups/public"
        }
      ]
    profiles: >
      [
        {
          "id": "foo.profile",
          "name": "foo.profile",
          "url": "http://foo.bar.profile",
          "properties": {
            "foo": "property-1",
            "bar": "property-2"
          }
        }
      ]
    plugin_groups: >
      [
        "some.plugin.group.id",
        "some.other.plugin.group.id"
      ]
    proxies: >
      [
        {
          "id": "foo-proxy",
          "active": "true",
          "protocol": "http",
          "host": "https://proxy.example.com",
          "port": "443",
          "username": "foo",
          "password": "bar",
          "nonProxyHosts": "noproxy1.example.com|noproxy2.example.com"
        }
      ]
    active_profiles: >
      [
        "some-profile"
      ]
    output_file: .m2/settings.xml

Output:

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              http://maven.apache.org/xsd/settings-1.0.0.xsd">

    <activeProfiles>
        <activeProfile>some-profile</activeProfile>
    </activeProfiles>

    <profiles>
        <profile>
            <id>github</id>
            <repositories>
                <repository>
                    <id>some-repository</id>
                    <name>some-repository-name</name>
                    <url>http://some.repository.url</url>
                    <releases>
                        <enabled>true</enabled>
                        <updatePolicy>always</updatePolicy>
                        <checksumPolicy>fail</checksumPolicy>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                        <updatePolicy>always</updatePolicy>
                        <checksumPolicy>fail</checksumPolicy>
                    </snapshots>
                </repository>
            </repositories>
            <pluginRepositories>
                <pluginRepository>
                    <id>some-plugin-repository</id>
                    <name>some-plugin-repository-name</name>
                    <url>http://some.plugin.repository.url</url>
                    <releases>
                        <enabled>true</enabled>
                    </releases>
                    <snapshots>
                        <enabled>false</enabled>
                    </snapshots>
                </pluginRepository>
            </pluginRepositories>
        </profile>
        <profile>
            <id>foo.profile</id>
            <name>foo.profile</name>
            <url>http://foo.bar.profile</url>
            <properties>
                <foo>property-1</foo>
                <bar>property-2</bar>
            </properties>
        </profile>
    </profiles>

    <servers>
        <server>
            <id>some-id</id>
            <username>${env.USER}</username>
            <password>${env.PASS}</password>
            <configuration>
                <httpConfiguration>
                    <all>
                        <usePreemptive>true</usePreemptive>
                    </all>
                </httpConfiguration>
            </configuration>
        </server>
    </servers>

    <mirrors>
        <mirror>
            <id>nexus</id>
            <mirrorOf>!my-org-snapshots,*</mirrorOf>
            <url>http://redacted/nexus/content/groups/public</url>
        </mirror>
    </mirrors>

    <pluginGroups>
        <pluginGroup>some.plugin.group.id</pluginGroup>
        <pluginGroup>some.other.plugin.group.id</pluginGroup>
    </pluginGroups>

    <proxies>
        <proxy>
            <id>foo-proxy</id>
            <active>true</active>
            <protocol>http</protocol>
            <host>https://proxy.example.com</host>
            <port>443</port>
            <username>foo</username>
            <password>bar</password>
            <nonProxyHosts>noproxy1.example.com|noproxy2.example.com</nonProxyHosts>
        </proxy>
    </proxies>

</settings>

Local Development

Install dependencies:

npm ci

Run linter:

npm run lint

Run tests:

npm test

Build distribution:

npm run build

Run actions locally with Act

brew install act
act -s GITHUB_TOKEN={token} -j {step}

Example: act -s GITHUB_TOKEN=ghp_xxxx -j test-basic

Origin and Acknowledgment

This project is a fork of whelk-io/maven-settings-xml-action, originally created by Zack Teater (whelk.io) with contributions from Jason Edstrom. The original repository was archived in 2024 after the v22 release, which upgraded the runtime from Node 16 to Node 20.

This fork is maintained by Marcel R. G. Berger (digitalfreedom.co.za) to keep the action compatible with current GitHub Actions runtime requirements.

License

Apache License 2.0

Name		Name	Last commit message	Last commit date
Latest commit History 297 Commits
.github		.github
dist		dist
src		src
template		template
test		test
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

maven-settings-xml-action

What this Action does

How it works

Migration from upstream

What changed in v23

Inputs

`servers`

`mirrors`

`repositories`

`plugin_repositories`

`plugin_groups`

`profiles`

`active_profiles`

`proxies`

`output_file`

Basic Usage

Full Usage

Local Development

Run actions locally with Act

Origin and Acknowledgment

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

maven-settings-xml-action

What this Action does

How it works

Migration from upstream

What changed in v23

Inputs

servers

mirrors

repositories

plugin_repositories

plugin_groups

profiles

active_profiles

proxies

output_file

Basic Usage

Full Usage

Local Development

Run actions locally with Act

Origin and Acknowledgment

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`servers`

`mirrors`

`repositories`

`plugin_repositories`

`plugin_groups`

`profiles`

`active_profiles`

`proxies`

`output_file`