= Environment

JReleaser can configure some of its fields from external sources. This allows keeping a stable configuration file and only
update the external sources to produce a new release. Values may be read from a Java properties file or from
environment variables, the file has precendence over the environment variables.

By default, the external properties file should be located at `~/.jreleaser/config.properties` however you may change
that location by setting/changing the value of the `JRELEASER_USER_HOME` environment variable or using the block
described next:

include::partial$legend.adoc[]

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# Configures environment sources.
# icon:dot-circle[]
environment:

  # Location of a properties file with key/value pairs
  # Each key must be prefixed with `JRELEASER_` and match
  # the environment variable it overrides.
  # icon:dot-circle[]
  variables: path/to/alternate/config.properties

  # Additional properties used when evaluating templates.
  # icon:dot-circle[]
  properties:
    foo: bar
----
TOML::
+
[source,toml]
[subs="+macros"]
----
# Configures environment sources.
# icon:dot-circle[]
[environment]

  # Location of a properties file with key/value pairs
  # Each key must be prefixed with `JRELEASER_` and match
  # the environment variable it overrides.
  # icon:dot-circle[]
  variables = "path/to/alternate/config.properties"

  # Additional properties used when evaluating templates.
  # icon:dot-circle[]
  properties.foo = "bar"
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
  // Configures environment sources.
  // icon:dot-circle[]
  "environment": {
    // Location of a properties file with key/value pairs
    // Each key must be prefixed with `JRELEASER_` and match
    // the environment variable it overrides.
    // icon:dot-circle[]
    "variables": "path/to/alternate/config.properties",

    // Additional properties used when evaluating templates.
    // icon:dot-circle[]
    "properties": {
      "foo": "bar"
    }
  }
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
  <!--
    Configures environment sources.
    icon:dot-circle[]
  -->
  <environment>
    <!--
      Location of a properties file with key/value pairs
      Each key must be prefixed with `JRELEASER_` and match
      the environment variable it overrides.
      icon:dot-circle[]
    -->
    <variables>path/to/alternate/config.properties</variables>

    <!--
     Additional properties used when evaluating templates.
     icon:dot-circle[]
    -->
    <properties>
      <foo>bar</foo>
    </properties>
  </environment>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  // Configures environment sources.
  // icon:dot-circle[]
  environment {
    // Location of a properties file with key/value pairs
    // Each key must be prefixed with `JRELEASER_` and match
    // the environment variable it overrides.
    // icon:dot-circle[]
    variables = 'path/to/alternate/config.properties'

    // Additional properties used when evaluating templates.
    // icon:dot-circle[]
    properties.put('foo', 'bar')
  }
}
----
====

Formats currently supported for the file configurable in the `variables` field are:

* `.properties`
* `.yml`
* `.toml`
* `.json`

[tabs]
====
PROPERTIES::
+
[source,properties]
[subs="+macros"]
.config.properties
----
JRELEASER_GITHUB_TOKEN = b9df0920aefcbfa69f57c4f02bae4396
----
YAML::
+
[source,yaml]
[subs="+macros"]
.config.yml
----
JRELEASER_GITHUB_TOKEN: b9df0920aefcbfa69f57c4f02bae4396
----
TOML::
+
[source,toml]
[subs="+macros"]
.config.toml
----
JRELEASER_GITHUB_TOKEN = "b9df0920aefcbfa69f57c4f02bae4396"
----
JSON::
+
[source,json]
[subs="+macros"]
.config.json
----
{
  "JRELEASER_GITHUB_TOKEN": "b9df0920aefcbfa69f57c4f02bae4396"
}
----
====

NOTE: The config file must use the appropriate file extension that matches the format in use.

IMPORTANT: The config file should have key/value pairs with no nesting. Each key maps to the corresponding environment
variable that requires a value.

TIP: Use the `yml` or `toml` formats for key/values that require multiple lines, such as JRELEASER_GPG_PUBLIC_KEY.

When using a format that supports multi-line strings be sure to follow these rules:

*Yaml*

 * Use a `|` as the sole character of the first line.
 * Indent every other line, typically with 2 spaces.

*Toml*

 * Do not indent lines unless the indentation must be part of the content.

As an example, the `JRELEASER_GPG_PUBLIC_KEY` key/value may be written as follows:

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
.config.yml
----
JRELEASER_GPG_PUBLIC_KEY: |
  -----BEGIN PGP PUBLIC KEY BLOCK----

  mQGiBEYVIwERBACndCqn1kKjVD8r2YjYAsqzNQet/U7wn6pIrvKd+23W+LH04tRY
  ...
  -----END PGP PUBLIC KEY BLOCK-----
----
TOML::
+
[source,toml]
[subs="+macros"]
.config.toml
----
JRELEASER_GPG_PUBLIC_KEY="""-----BEGIN PGP PUBLIC KEY BLOCK----

mQGiBEYVIwERBACndCqn1kKjVD8r2YjYAsqzNQet/U7wn6pIrvKd+23W+LH04tRY
...
-----END PGP PUBLIC KEY BLOCK-----"""
----
====

Take special note that the empty line at the 2nd row is required, otherwise you may get an error similar
to the following one:

[source]
----
Caused by: http://java.io.IOException: public key ring doesn't start with public key tag: tag 0xffffffff
----

== Maven

JReleaser will honor Maven project properties. These properties can be defined in several ways:

- on the command line by using the `-D` flag.
- on a `pom.xml` by using the `<properties>` block.
- on a settings file using the `<properties>` block inside an active profile.

JReleaser should be able to handle properties define in any of these ways.
Precedence is:

- values defined in the model.
- values defined as Maven properties.
- values defined in `<releaser><environment><variables>`.
- environment variables.

Keys must either be fully uppercase words separated by underscores (`_`) or fully lowercase words separated by dots (`.`).
The uppercase variant has precedence over the lowercase variant. For example, the Github token may be defined in
`~/.m2/settings.xml` as:

[source,xml]
[subs="verbatim"]
.settings.xml
----
<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
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <profiles>
      <profile>
        <id>jreleaser</id>
        <activation>
          <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
          <JRELEASER_GITHUB_TOKEN>2ee1ce8ff570e0bOVEdrZvie8792058</JRELEASER_GITHUB_TOKEN>
        </properties>
      </profile>
    </profiles>
</settings>
----

Or as

[source,xml]
[subs="verbatim"]
.settings.xml
----
<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
                      https://maven.apache.org/xsd/settings-1.0.0.xsd">

    <profiles>
      <profile>
        <id>jreleaser</id>
        <activation>
          <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
          <jreleaser.github.token>2ee1ce8ff570e0bOVEdrZvie8792058</jreleaser.github.token>
        </properties>
      </profile>
    </profiles>
</settings>
----

== Gradle

JReleaser will honor Gradle project properties. These properties can be defined in several ways:

- on the command line by using the `-P` flag.
- on a `gradle.properties` file adjacent to the project.
- on a `gradle.properties` file located at `~/.gradle`.

JReleaser should be able to handle properties define in any of these ways.
Precedence is:
- values defined in the model.
- values defined as Gradle project properties.
- values defined in `jreleaser.environment.variables`.
- environment variables.

Keys must either be fully uppercase words separated by underscores (`_`) or fully lowercase words separated by dots (`.`).
The uppercase variant has precedence over the lowercase variant. For example, the Github token may be defined in
`/.gradle/gradle.properties` as:

[source]
.gradle.properties
----
JRELEASER_GITHUB_TOKEN = 2ee1ce8ff570e0bOVEdrZvie8792058
----

Or as:

[source]
.gradle.properties
----
jreleaser.github.token = 2ee1ce8ff570e0bOVEdrZvie8792058
----

== Keys & Values

The following key/values may be defined as properties or as environment variables:

=== Project

[%header, cols="<1,<1", width="100%"]
|===
| Key                                | Description
| JRELEASER_PROJECT_NAME             | the project name
| JRELEASER_PROJECT_VERSION          | the project version
| JRELEASER_PROJECT_VERSION_PATTERN  | the project version pattern
| JRELEASER_PROJECT_SNAPSHOT_PATTERN | a regex to determine if the project version is snapshot
|===

=== Release

[%header, cols="<1,<1", width="100%"]
|===
| Key                      | Description
| JRELEASER_TAG_NAME       | the release tag name
| JRELEASER_RELEASE_NAME   | the release name
| JRELEASER_MILESTONE_NAME | the milestone name/title
| JRELEASER_BRANCH         | the release branch
| JRELEASER_OVERWRITE      | overwrite an existing release
| JRELEASER_UPDATE         | update an existing release
| JRELEASER_SKIP_TAG       | skip tagging the release
| JRELEASER_PRERELEASE     | release is a prerelease (github/gitea)
| JRELEASER_DRAFT          | release is a draft (github/gitea)
| JRELEASER_GITHUB_TOKEN   | a GitHub token with `repo` scope
| JRELEASER_GITLAB_TOKEN   | a GitLab token with `api` scope
| JRELEASER_GITEA_TOKEN    | a Gitea personal token
| JRELEASER_CODEBERG_TOKEN | a Codeberg personal token
| JRELEASER_GENERIC_TOKEN  | a git personal token or password
|===

=== Signing

[%header, cols="<1,<1", width="100%"]
|===
| Key                      | Description
| JRELEASER_GPG_PASSPHRASE | the passphrase to decrypt the secret key
| JRELEASER_GPG_PUBLIC_KEY | the public key used for signing
| JRELEASER_GPG_SECRET_KEY | the secret key used for signing
|===

=== Artifactory

[%header, cols="<1,<1", width="100%"]
|===
| Key                                    | Description
| JRELEASER_ARTIFACTORY_${NAME}_USERNAME | a username matching the named Artifactory instance
| JRELEASER_ARTIFACTORY_${NAME}_PASSWORD | a password/token matching the named Artifactory instance
|===

=== Http

[%header, cols="<1,<1", width="100%"]
|===
| Key                             | Description
| JRELEASER_HTTP_${NAME}_USERNAME | a username matching the named HTTP server
| JRELEASER_HTTP_${NAME}_PASSWORD | a password/token matching the named HTTP server
|===

=== Docker

[%header, cols="<1,<1", width="100%"]
|===
| Key                               | Description
| JRELEASER_DOCKER_${NAME}_PASSWORD | a docker password matching the named server
|===

=== Homebrew

[%header, cols="<1,<1", width="100%"]
|===
| Key                               | Description
| JRELEASER_HOMEBREW_GITHUB_TOKEN   | a GitHub token with `repo` scope
| JRELEASER_HOMEBREW_GITLAB_TOKEN   | a GitLab token with `api` scope
| JRELEASER_HOMEBREW_GITEA_TOKEN    | a Gitea personal token
| JRELEASER_HOMEBREW_CODEBERG_TOKEN | a Codeberg personal token
|===

=== Chocolatey

[%header, cols="<1,<1", width="100%"]
|===
| Key                                 | Description
| JRELEASER_CHOCOLATEY_GITHUB_TOKEN   | a GitHub token with `repo` scope
| JRELEASER_CHOCOLATEY_GITLAB_TOKEN   | a GitLab token with `api` scope
| JRELEASER_CHOCOLATEY_GITEA_TOKEN    | a Gitea personal token
| JRELEASER_CHOCOLATEY_CODEBERG_TOKEN | a Codeberg personal token
|===

=== JBang

[%header, cols="<1,<1", width="100%"]
|===
| Key                            | Description
| JRELEASER_JBANG_GITHUB_TOKEN   | a GitHub token with `repo` scope
| JRELEASER_JBANG_GITLAB_TOKEN   | a GitLab token with `api` scope
| JRELEASER_JBANG_GITEA_TOKEN    | a Gitea personal token
| JRELEASER_JBANG_CODEBERG_TOKEN | a Codeberg personal token
|===

=== Scoop

[%header, cols="<1,<1", width="100%"]
|===
| Key                            | Description
| JRELEASER_SCOOP_GITHUB_TOKEN   | a GitHub token with `repo` scope
| JRELEASER_SCOOP_GITLAB_TOKEN   | a GitLab token with `api` scope
| JRELEASER_SCOOP_GITEA_TOKEN    | a Gitea personal token
| JRELEASER_SCOOP_CODEBERG_TOKEN | a Codeberg personal token
|===

=== Snap

[%header, cols="<1,<1", width="100%"]
|===
| Key                           | Description
| JRELEASER_SNAP_GITHUB_TOKEN   | a GitHub token with `repo` scope
| JRELEASER_SNAP_GITLAB_TOKEN   | a GitLab token with `api` scope
| JRELEASER_SNAP_GITEA_TOKEN    | a Gitea personal token
| JRELEASER_SNAP_CODEBERG_TOKEN | a Codeberg personal token
|===

=== Discord

[%header, cols="<1,<1", width="100%"]
|===
| Key                       | Description
| JRELEASER_DISCORD_WEBHOOK | the webhook URL
|===

=== Gitter

[%header, cols="<1,<1", width="100%"]
|===
| Key                      | Description
| JRELEASER_GITTER_WEBHOOK | the webhook URL
|===

=== Mail

[%header, cols="<1,<1", width="100%"]
|===
| Key                     | Description
| JRELEASER_MAIL_PASSWORD | the password required for sending e-mails
|===

=== Mastodon

[%header, cols="<1,<1", width="100%"]
|===
| Key                             | Description
| JRELEASER_MASTODON_ACCESS_TOKEN | the access token required by Mastodon
|===

=== Mattermost

[%header, cols="<1,<1", width="100%"]
|===
| Key                          | Description
| JRELEASER_MATTERMOST_WEBHOOK | the webhook URL
|===

=== Sdkman

[%header, cols="<1,<1", width="100%"]
|===
| Key                             | Description
| JRELEASER_SDKMAN_CONSUMER_KEY   | the consumer key required by SdkMan!
| JRELEASER_SDKMAN_CONSUMER_TOKEN | the consumer token required by SdkMan!
|===

=== Slack

[%header, cols="<1,<1", width="100%"]
|===
| Key                     | Description
| JRELEASER_SLACK_TOKEN   | a bot or a personal Slack token
| JRELEASER_SLACK_WEBHOOK | the webhook URL
|===

=== Teams

[%header, cols="<1,<1", width="100%"]
|===
| Key                     | Description
| JRELEASER_TEAMS_WEBHOOK | the webhook URL
|===

=== Twitter

[%header, cols="<1,<1", width="100%"]
|===
| Key                                   | Description
| JRELEASER_TWITTER_CONSUMER_KEY        | the consumer key required by Twitter
| JRELEASER_TWITTER_CONSUMER_TOKEN      | the consumer token required by Twitter
| JRELEASER_TWITTER_ACCESS_TOKEN        | the access token required by Twitter
| JRELEASER_TWITTER_ACCESS_TOKEN_SECRET | the access token secret required by Twitter
|===

=== Zulip

[%header, cols="<1,<1", width="100%"]
|===
| Key                     | Description
| JRELEASER_ZULIP_API_KEY | the api key required by Zulip
|===


