Skip to content

Document the environment.override flag #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
exoego wants to merge 1 commit into
base: development
Choose a base branch
from
Open

Document the environment.override flag #110

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions docs/modules/reference/pages/environment.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,12 @@ environment:
# icon:dot-circle[]
variables: path/to/alternate/config.properties

# Lets external sources take precedence over values
# explicitly set in the DSL.
# Defaults to `false`.
# icon:dot-circle[] icon:eye-slash[]
override: true

# Additional properties used when evaluating templates.
# icon:dot-circle[]
properties:
Expand All @@ -55,6 +61,12 @@ TOML::
# icon:dot-circle[]
variables = "path/to/alternate/config.properties"

# Lets external sources take precedence over values
# explicitly set in the DSL.
# Defaults to `false`.
# icon:dot-circle[] icon:eye-slash[]
override = true

# Additional properties used when evaluating templates.
# icon:dot-circle[]
properties.foo = "bar"
Expand All @@ -76,6 +88,12 @@ JSON::
// icon:dot-circle[]
"variables": "path/to/alternate/config.properties",

// Lets external sources take precedence over values
// explicitly set in the DSL.
// Defaults to `false`.
// icon:dot-circle[] icon:eye-slash[]
"override": true,

// Additional properties used when evaluating templates.
// icon:dot-circle[]
"properties": {
Expand Down Expand Up @@ -105,6 +123,14 @@ Maven::
-->
<variables>path/to/alternate/config.properties</variables>

<!--
Lets external sources take precedence over values
explicitly set in the DSL.
Defaults to `false`.
icon:dot-circle[] icon:eye-slash[]
-->
<override>true</override>

<!--
Additional properties used when evaluating templates.
icon:dot-circle[]
Expand Down Expand Up @@ -132,6 +158,12 @@ jreleaser {
// icon:dot-circle[]
variables = 'path/to/alternate/config.properties'

// Lets external sources take precedence over values
// explicitly set in the DSL.
// Defaults to `false`.
// icon:dot-circle[] icon:eye-slash[]
override = true

// Additional properties used when evaluating templates.
// icon:dot-circle[]
properties.put('foo', 'bar')
Expand Down Expand Up @@ -383,6 +415,32 @@ Settings will be evaluated in the following order:
* Project configuration (`.env` file).
* User configuration (`$XDG_CONFIG_HOME/jreleaser`, `$JRELEASER_USER_HOME`, `$HOME/.jreleaser`).

=== Overriding the DSL

A value written in the DSL normally wins, which means external sources only fill in the fields you left out. Set
`environment.override` to move the DSL to the bottom of the list instead, so a release may be adjusted from the outside
without keeping a second configuration file. The remaining entries keep their relative order, so a system property
still wins over an environment variable.

This is useful on CI, where the same configuration file has to produce a different release:

[source,yaml]
[subs="+macros"]
..github/workflows/release.yml
----
- uses: jreleaser/release-action@v2
env:
JRELEASER_ENVIRONMENT_OVERRIDE: true
JRELEASER_PROJECT_VERSION: ${{ github.ref_name }}
JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
----

Here `project.version` resolves to the tag that triggered the workflow even when the configuration file sets a version
of its own. Drop `JRELEASER_ENVIRONMENT_OVERRIDE` and the configured version wins again.

NOTE: Fields with no matching key are unaffected, as there is nothing external to read them from. Use the `env` command
described in the next section to see which keys exist.

== Inspection

Use the `env` command to display environment variable key names as resolved by the tool
Expand All @@ -399,6 +457,18 @@ You'll also find these key names in the respective `trace.log` file.
The value of the following properties may be resolved from an environment variable or a system
property. The system property takes precedence over the environment variable.

=== Environment Override

Lets external sources take precedence over values explicitly set in the DSL, as described under Precedence Order.
Setting this key is equivalent to setting `environment.override`, and leaves the configuration file untouched. An
explicit `environment.override` wins over this key.

[horizontal]
System Property:: jreleaser.environment.override
Environment Variable:: JRELEASER_ENVIRONMENT_OVERRIDE
Default Value:: false
Possible Values:: true, false

=== HTTP Logger

Logs HTTP operations to the `trace.log` file.
Expand Down