AWS S3
Uploads artifacts, files, and signatures to an AWS S3 bucket.
-
An AWS account with S3 access.
Configuration
Legend:
-
required
-
optional
-
may use environment variable
-
accepts Name Templates
#
upload:
#
s3:
# Uploaders require a name.
#
app:
# Enables or disables the uploader.
# Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
# Defaults to `NEVER`.
#
active: ALWAYS
# Defines the connection timeout in seconds.
# Defaults to `20`.
#
connectTimeout: 20
# Defines the read timeout in seconds.
# Defaults to `60`.
#
readTimeout: 60
# Upload files.
# Defaults to `true`.
#
files: true
# Upload distribution artifacts.
# Defaults to `true`.
#
artifacts: true
# Release checksum files.
# Defaults to `true`.
#
checksums: true
# Upload signatures.
# Defaults to `true`.
#
signatures: true
# Upload catalogs.
# Defaults to `true`.
#
catalogs: true
# Additional properties used when evaluating templates.
#
extraProperties:
# Key will be capitalized and prefixed with `s3`, i.e, `s3Foo`.
foo: bar
# The region where the S3 bucket is located.
#
region: us-east-2
# The name of the bucket.
#
bucket: releases
# The artifact path within the bucket.
#
path: '{{projectName}}/{{tagName}}/{{artifactFile}}'
# Custom download URL.
# Required if a custom endpoint is defined.
#
downloadUrl: 'https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}'
# The accessKeyId required for authorization.
#
accessKeyId: __USE_ENVIRONMENT_VARIABLE__
# The secretKey required for authorization.
#
secretKey: __USE_ENVIRONMENT_VARIABLE__
# The AWS sessionToken when you use temporal credentials.
#
sessionToken: __USE_ENVIRONMENT_VARIABLE__
# The endpoint to use for S3 service in case some other S3 compatible service is used.
#
endpoint: 's3.{{region}}.example.com'
# Additional headers to be sent to the server.
# Values accept Name Templates.
#
headers:
'X-ARTIFACT-PLATFORM': '{{artifactPlatform}}'
# Uploaders require a name.
#
[upload.s3.app]
# Enables or disables the uploader.
# Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
# Defaults to `NEVER`.
#
active = "ALWAYS"
# Defines the connection timeout in seconds.
# Defaults to `20`.
#
connectTimeout = 20
# Defines the read timeout in seconds.
# Defaults to `60`.
#
readTimeout = 60
# Upload files.
# Defaults to `true`.
#
files = true
# Upload distribution artifacts.
# Defaults to `true`.
#
artifacts = true
# Release checksum files.
# Defaults to `true`.
#
checksums = true
# Upload signatures.
# Defaults to `true`.
#
signatures = true
# Upload catalogs.
# Defaults to `true`.
#
catalogs = true
# Additional properties used when evaluating templates.
#
extraProperties.foo = "bar"
# Key will be capitalized and prefixed with `s3`, i.e, `s3Foo`.
# The region where the S3 bucket is located.
#
region = "us-east-2"
# The name of the bucket.
#
bucket = "releases"
# The artifact path within the bucket.
#
path = "{{projectName}}/{{tagName}}/{{artifactFile}}"
# Custom download URL.
# Required if a custom endpoint is defined.
#
downloadUrl = "https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}"
# The accessKeyId required for authorization.
#
accessKeyId = "__USE_ENVIRONMENT_VARIABLE__"
# The secretKey required for authorization.
#
secretKey = "__USE_ENVIRONMENT_VARIABLE__"
# The AWS sessionToken when you use temporal credentials.
#
sessionToken = "__USE_ENVIRONMENT_VARIABLE__"
# The endpoint to use for S3 service in case some other S3 compatible service is used.
#
endpoint = "s3.{{region}}.example.com"
# Additional headers to be sent to the server.
# Values accept Name Templates.
#
headers."X-ARTIFACT-PLATFORM" = "{{artifactPlatform}}"
{
//
"upload": {
//
"s3": {
// Uploaders require a name.
//
"app": {
// Enables or disables the uploader.
// Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
// Defaults to `NEVER`.
//
"active": "ALWAYS",
// Defines the connection timeout in seconds.
// Defaults to `20`.
//
"connectTimeout": 20,
// Defines the read timeout in seconds.
// Defaults to `60`.
//
"readTimeout": 60,
// Upload files.
// Defaults to `true`.
//
"files": true,
// Upload distribution artifacts.
// Defaults to `true`.
//
"artifacts": true,
// Release checksum files.
// Defaults to `true`.
//
"checksums": true,
// Upload signatures.
// Defaults to `true`.
//
"signatures": true,
// Upload catalogs.
// Defaults to `true`.
//
"catalogs": true,
// Additional properties used when evaluating templates.
//
"extraProperties": {
// Key will be capitalized and prefixed with `s3`, i.e, `s3Foo`.
"foo": "bar"
},
// The region where the S3 bucket is located.
//
"region": "us-east-2",
// The name of the bucket.
//
"bucket": "releases",
// The artifact path within the bucket.
//
"path": "{{projectName}}/{{tagName}}/{{artifactFile}}",
// Custom download URL.
// Required if a custom endpoint is defined.
//
"downloadUrl": "https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}",
// The accessKeyId required for authorization.
//
"accessKeyId": "__USE_ENVIRONMENT_VARIABLE__",
// The secretKey required for authorization.
//
"secretKey": "__USE_ENVIRONMENT_VARIABLE__",
// The AWS sessionToken when you use temporal credentials.
//
"sessionToken": "__USE_ENVIRONMENT_VARIABLE__",
// The endpoint to use for S3 service in case some other S3 compatible service is used.
//
"endpoint": "s3.{{region}}.example.com",
// Additional headers to be sent to the server.
// Values accept Name Templates.
//
"headers": {
"X-ARTIFACT-PLATFORM": "{{artifactPlatform}}"
}
}
}
}
}
<jreleaser>
<!--
-->
<upload>
<!--
-->
<s3>
<!--
Uploaders require a name.
-->
<app>
<!--
Enables or disables the distribution.
Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
Defaults to `NEVER`.
-->
<active>ALWAYS</active>
<!--
Defines the connection timeout in seconds.
Defaults to `20`.
-->
<connectTimeout>20</connectTimeout>
<!--
Defines the read timeout in seconds.
Defaults to `60`.
-->
<readTimeout>60</readTimeout>
<!--
Upload files.
Defaults to `true`.
-->
<files>true</files>
<!--
Upload distribution artifacts.
Defaults to `true`.
-->
<artifacts>true</artifacts>
<!--
Release checksum files.
Defaults to `true`.
-->
<checksums>true</checksums>
<!--
Upload signatures.
Defaults to `true`.
-->
<signatures>true</signatures>
<!--
Upload catalogs.
Defaults to `true`.
-->
<catalogs>true</catalogs>
<!--
Additional properties used when evaluating templates.
-->
<extraProperties>
<!--
Key will be capitalized and prefixed with `s3`, i.e, `s3Foo`.
-->
<foo>bar</foo>
</extraProperties>
<!--
The region where the S3 bucket is located.
-->
<region>us-east-2</region>
<!--
The name of the bucket.
-->
<bucket>releases</bucket>
<!--
The artifact path within the bucket.
-->
<path>{{projectName}}/{{tagName}}/{{artifactFile}}</path>
<!--
Custom download URL.
Required if a custom endpoint is defined.
-->
<downloadUrl>https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}</downloadUrl>
<!--
The accessKeyId required for authorization.
-->
<accessKeyId>__USE_ENVIRONMENT_VARIABLE__</accessKeyId>
<!--
The secretKey required for authorization.
-->
<secretKey>__USE_ENVIRONMENT_VARIABLE__</secretKey>
<!--
The AWS sessionToken when you use temporal credentials.
-->
<sessionToken>__USE_ENVIRONMENT_VARIABLE__</sessionToken>
<!--
The endpoint to use for S3 service in case some other S3 compatible service is used.
-->
<endpoint>s3.{{region}}.example.com</endpoint>
<!--
Additional headers to be sent to the server.
Values accept Name Templates.
-->
<headers>
<X-ARTIFACT-PLATFORM>{{artifactPlatform}}</X-ARTIFACT-PLATFORM>
</headers>
</app>
</s3>
</upload>
</jreleaser>
jreleaser {
//
upload {
//
s3 {
// Uploaders require a name.
//
app {
// Enables or disables the uploader.
// Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
// Defaults to `NEVER`.
//
active = 'ALWAYS'
// Defines the connection timeout in seconds.
// Defaults to `20`.
//
connectTimeout = 20
// Defines the read timeout in seconds.
// Defaults to `60`.
//
readTimeout = 60
// Upload files.
// Defaults to `true`.
//
files = true
// Upload distribution artifacts.
// Defaults to `true`.
//
artifacts = true
// Release checksum files.
// Defaults to `true`.
//
checksums = true
// Upload signatures.
// Defaults to `true`.
//
signatures = true
// Upload catalogs.
// Defaults to `true`.
//
catalogs = true
// Additional properties used when evaluating templates.
// Key will be capitalized and prefixed with `s3`, i.e, `s3Foo`.
//
extraProperties.put('foo', 'bar')
// The region where the S3 bucket is located.
//
region = 'us-east-2'
// The name of the bucket.
//
bucket = 'releases'
// The artifact path within the bucket.
//
path = '{{projectName}}/{{tagName}}/{{artifactFile}}'
// Custom download URL.
// Required if a custom endpoint is defined.
//
downloadUrl = 'https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}'
// The accessKeyId required for authorization.
//
accessKeyId = '__USE_ENVIRONMENT_VARIABLE__'
// The secretKey required for authorization.
//
secretKey = '__USE_ENVIRONMENT_VARIABLE__'
// The AWS sessionToken when you use temporal credentials.
//
sessionToken = '__USE_ENVIRONMENT_VARIABLE__'
// The endpoint to use for S3 service in case some other S3 compatible service is used.
//
endpoint = 's3.{{region}}.example.com'
// Additional headers to be sent to the server.
// Values accept Name Templates.
//
headers.put('X-ARTIFACT-PLATFORM', '{{artifactPlatform}}')
}
}
}
}
Environment
When not explicitly set, the value of the following properties may be resolved from an environment variable or a system property as shown in the table. The system property takes precedence over the environment variable.
System Property | Environment Variable |
---|---|
active |
|
jreleaser.upload.s3.${name}.active |
JRELEASER_UPLOAD_S3_${name}_ACTIVE |
region |
|
jreleaser.upload.s3.${name}.region |
JRELEASER_UPLOAD_S3_${name}_REGION |
bucket |
|
jreleaser.upload.s3.${name}.bucket |
JRELEASER_UPLOAD_S3_${name}_BUCKET |
accessKeyId |
|
jreleaser.upload.s3.${name}.access.key.id |
JRELEASER_UPLOAD_S3_${name}_ACCESS_KEY_ID |
secretKey |
|
jreleaser.upload.s3.${name}.secret.key |
JRELEASER_UPLOAD_S3_${name}_SECRET_KEY |
sessionToken |
|
jreleaser.upload.s3.${name}.session.token |
JRELEASER_UPLOAD_S3_${name}_SESSION_TOKEN |
path |
|
jreleaser.upload.s3.${name}.path |
JRELEASER_UPLOAD_S3_${name}_PATH |
downloadUrl |
|
jreleaser.upload.s3.${name}.download.url |
JRELEASER_UPLOAD_S3_${name}_DOWNLOAD_URL |
endpoint |
|
jreleaser.upload.s3.${name}.endpoint |
JRELEASER_UPLOAD_S3_${name}_ENDPOINT |
Substitute ${name} for the value of the named instance. |
Space (' '), underscore (_
), and dash (-
) will be replaced by dot (.
) to separate tokens in the System property.
Space (' '), dash (-
), and dot (.
) will be replaced by underscore (_
) to separate tokens in the environment variable,
such that:
${name} | System Property | Environment Variable |
---|---|---|
foobar |
|
|
fooBar |
|
|
foo bar |
|
|
foo-bar |
|
|
foo_bar |
|
|
foo.bar |
|
|
DownloadUrl
The downloadUrl is the URL used to download artifacts from.
An example configuration may look like
downloadUrl: 'https://s3.amazonaws.com/{{projectName}}/downloads/{{projectVersion}}/{{artifactFile}}'
.
And will result in a final URL like
https://s3.amazonaws.com/app/downloads/1.0.0/app-1.0.0.zip
.
If a custom endpoint is defined then this property must be set as well.
Artifacts may define an extra property following the <uploaderType><capitalizedUploaderName>Path
format to override
the default path within the bucket. This does not work for custom endpoints. For example
upload:
s3:
app:
active: ALWAYS
distributions:
app:
artifacts:
- path: target/distributions/{{distributionName}}/{{distributionName}}-{{projectVersion}}.zip
extraProperties:
s3AppPath: 'releases/{{artifactFile}}'
- path: target/distributions/{{distributionName}}/{{distributionName}}-{{projectVersion}}.tar.gz
These settings will upload app-1.0.0.zip
and app-1.0.0.zip.asc
to releases/app-1.0.0.zip
and releases/app-1.0.0.zip.asc
respectively while app-1.0.0.tar.gz
and app-1.0.0.tar.gz.asc
will be uploaded to their default paths, those being
app/v1.0.0/app-1.0.0.tar.gz
and app/v1.0.0/app-1.0.0.tar.gz.asc
respectively.
Credentials
JReleaser uses the DefaultAWSCredentialsProviderChain
to look up the AWS credentials. If you want to override the credentials feel free to set accessKeyId
and secretKey
and (optionally depends on configuration) sessionToken
. If these properties are set then JReleaser will ignore DefaultAWSCredentialsProviderChain
.
Skip Upload
Distributions and Artifacts may define extra properties that may stop them from being uploaded. These properties must conform to the following rules:
-
skipUpload
: skipped from all uploaders. -
skipUpload<type>
: skipped from the typed uploader. -
skipUpload<type><name>
: skipped from the typed and named uploader.
Where <type>
resolves to S3
and <name>
resolves to the capitalized name of the S3 instance, such
that:
-
if the name is
foo
the resulting property key isskipUploadS3Foo
. -
if the name is
fooBar
the resulting property key isskipUploadS3FooBar
. -
if the name is
foo-bar
the resulting property key isskipUploadS3FooBar
.