AWS S3
Uploads artifacts, files, and signatures to an AWS S3 bucket.
-
An AWS account with S3 access.
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
# 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.
# If left unspecified, the `JRELEASER_S3_${name}_REGION`
# environment variable must be defined.
#
region: us-east-2
# The name of the bucket.
# If left unspecified, the `JRELEASER_S3_${name}_BUCKET`
# environment variable must be defined.
#
bucket: releases
# The artifact path within the bucket.
# If left unspecified, the `JRELEASER_S3_${name}_PATH`
# environment variable may be defined.
#
path: '{{projectName}}/{{tagName}}/{{artifactFile}}'
# Custom download URL.
# If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
# environment variable may be defined.
# Required if a custom endpoint is defined.
#
downloadUrl: 'https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}'
# The accessKeyId required for authorization.
# If left unspecified, the `JRELEASER_S3_${name}_ACCESS_KEY_ID`
# environment variable must be defined.
#
accessKeyId: __DO_NOT_SET_HERE__
# The secretKey required for authorization.
# If left unspecified, the `JRELEASER_S3_${name}_SECRET_KEY`
# environment variable must be defined.
#
secretKey: __DO_NOT_SET_HERE__
# The AWS sessionToken when you use temporal credentials.
# If left unspecified, the `JRELEASER_S3_${name}_SESSION_TOKEN`
# environment variable must be defined.
#
sessionToken: __DO_NOT_SET_HERE__
# The endpoint to use for S3 service in case some other S3 compatible service is used.
# If left unspecified, the `JRELEASER_S3_${name}_ENDPOINT`
# environment variable may be defined.
#
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
# 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.
# If left unspecified, the `JRELEASER_S3_${name}_REGION`
# environment variable must be defined.
#
region = "us-east-2"
# The name of the bucket.
# If left unspecified, the `JRELEASER_S3_${name}_BUCKET`
# environment variable must be defined.
#
bucket = "releases"
# The artifact path within the bucket.
# If left unspecified, the `JRELEASER_S3_${name}_PATH`
# environment variable may be defined.
#
path = "{{projectName}}/{{tagName}}/{{artifactFile}}"
# Custom download URL.
# If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
# environment variable may be defined.
# Required if a custom endpoint is defined.
#
downloadUrl = "https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}"
# The accessKeyId required for authorization.
# If left unspecified, the `JRELEASER_S3_${name}_ACCESS_KEY_ID`
# environment variable must be defined.
#
accessKeyId = "__DO_NOT_SET_HERE__"
# The secretKey required for authorization..
# If left unspecified, the `JRELEASER_S3_${name}_SECRET_KEY`
# environment variable must be defined.
#
secretKey = "__DO_NOT_SET_HERE__"
# The AWS sessionToken when you use temporal credentials.
# If left unspecified, the `JRELEASER_S3_${name}_SESSION_TOKEN`
# environment variable must be defined.
#
sessionToken = "__DO_NOT_SET_HERE__"
# The endpoint to use for S3 service in case some other S3 compatible service is used.
# If left unspecified, the `JRELEASER_S3_${name}_ENDPOINT`
# environment variable may be defined.
#
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,
// 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.
// If left unspecified, the `JRELEASER_S3_${name}_REGION`
// environment variable must be defined.
//
"region": "us-east-2",
// The name of the bucket.
// If left unspecified, the `JRELEASER_S3_${name}_BUCKET`
// environment variable must be defined.
//
"bucket": "releases",
// The artifact path within the bucket.
// If left unspecified, the `JRELEASER_S3_${name}_PATH`
// environment variable may be defined.
//
"path": "{{projectName}}/{{tagName}}/{{artifactFile}}",
// Custom download URL.
// If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
// environment variable may be defined.
// Required if a custom endpoint is defined.
//
"downloadUrl": "https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}",
// The accessKeyId required for authorization.
// If left unspecified, the `JRELEASER_S3_${name}_ACCESS_KEY_ID`
// environment variable must be defined.
//
"accessKeyId": "__DO_NOT_SET_HERE__",
// The secretKey required for authorization.
// If left unspecified, the `JRELEASER_S3_${name}_SECRET_KEY`
// environment variable must be defined.
//
"secretKey": "__DO_NOT_SET_HERE__",
// The AWS sessionToken when you use temporal credentials.
// If left unspecified, the `JRELEASER_S3_${name}_SESSION_TOKEN`
// environment variable must be defined.
//
"sessionToken": "__DO_NOT_SET_HERE__",
// The endpoint to use for S3 service in case some other S3 compatible service is used.
// If left unspecified, the `JRELEASER_S3_${name}_ENDPOINT`
// environment variable may be defined.
//
"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>
<!--
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.
If left unspecified, the `JRELEASER_S3_${name}_REGION`
environment variable must be defined.
-->
<region>us-east-2</region>
<!--
The name of the bucket.
If left unspecified, the `JRELEASER_S3_${name}_BUCKET`
environment variable must be defined.
-->
<bucket>releases</bucket>
<!--
If left unspecified, the `JRELEASER_S3_${name}_PATH`
environment variable may be defined.
-->
<path>{{projectName}}/{{tagName}}/{{artifactFile}}</path>
<!--
Custom download URL.
If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
environment variable may be defined.
Required if a custom endpoint is defined.
-->
<downloadUrl>https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}</downloadUrl>
<!--
The accessKeyId required for authorization.
If left unspecified, the `JRELEASER_S3_${name}_ACCESS_KEY_ID`
environment variable must be defined.
-->
<accessKeyId>__DO_NOT_SET_HERE__</accessKeyId>
<!--
The secretKey required for authorization.
If left unspecified, the `JRELEASER_S3_${name}_SECRET_KEY`
environment variable must be defined.
-->
<secretKey>__DO_NOT_SET_HERE__</secretKey>
<!--
The AWS sessionToken when you use temporal credentials.
If left unspecified, the `JRELEASER_S3_${name}_SESSION_TOKEN`
environment variable must be defined.
-->
<sessionToken>__DO_NOT_SET_HERE__</sessionToken>
<!--
The endpoint to use for S3 service in case some other S3 compatible service is used.
If left unspecified, the `JRELEASER_S3_${name}_ENDPOINT`
environment variable may be defined.
-->
<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
// 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.
// If left unspecified, the `JRELEASER_S3_${name}_REGION`
// environment variable must be defined.
//
region = 'us-east-2'
// The name of the bucket.
// If left unspecified, the `JRELEASER_S3_${name}_BUCKET`
// environment variable must be defined.
//
bucket = 'releases'
// The artifact path within the bucket.
// If left unspecified, the `JRELEASER_S3_${name}_PATH`
// environment variable may be defined.
//
path = '{{projectName}}/{{tagName}}/{{artifactFile}}'
// Custom download URL.
// If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
// environment variable may be defined.
// Required if a custom endpoint is defined.
//
downloadUrl = 'https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFile}}'
// The accessKeyId required for authorization.
// If left unspecified, the `JRELEASER_S3_${name}_ACCESS_KEY_ID`
// environment variable must be defined.
//
accessKeyId = '__DO_NOT_SET_HERE__'
// The secretKey required for authorization.
// If left unspecified, the `JRELEASER_S3_${name}_SECRET_KEY`
// environment variable must be defined.
//
secretKey = '__DO_NOT_SET_HERE__'
// The AWS sessionToken when you use temporal credentials.
// If left unspecified, the `JRELEASER_S3_${name}_SESSION_TOKEN`
// environment variable must be defined.
//
sessionToken = '__DO_NOT_SET_HERE__'
// The endpoint to use for S3 service in case some other S3 compatible service is used.
// If left unspecified, the `JRELEASER_S3_${name}_ENDPOINT`
// environment variable may be defined.
//
endpoint = 's3.{{region}}.example.com'
// Additional headers to be sent to the server.
// Values accept Name Templates.
//
headers.put('X-ARTIFACT-PLATFORM', '{{artifactPlatform}}')
}
}
}
}
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
.
AccessKeyId
The accessKeyId will be stored in an environment variable. The configured name of the S3 server will be used. This means that the name per configured instance needs to be unique.
The name of the environment variable will be JRELEASER_S3_NAME_ACCESS_KEY_ID
. If your instance is named production
,
you can store the accessKeyId in the environment variable JRELEASER_S3_PRODUCTION_ACCESS_KEY_ID
. The name will be
transformed to uppercase.
If a configured accessKeyId is found in the configuration file, then the environment variable is not used at all.
SecretKey
The secretKey will be stored in an environment variable. The configured name of the S3 server will be used. This means that the name per configured instance needs to be unique.
The name of the environment variable will be JRELEASER_S3_NAME_SECRET_KEY
. If your instance is named production
,
you need to store the secret in the environment variable JRELEASER_S3_PRODUCTION_SECRET_KEY
. The name will be
transformed to uppercase.
SessionToken
The sessionToken will be stored in an environment variable. The configured name of the S3 server will be used. This means that the name per configured instance needs to be unique.
The name of the environment variable will be JRELEASER_S3_NAME_SESSION_TOKEN
. If your instance is named production
,
you need to store the secret in the environment variable JRELEASER_S3_PRODUCTION_SESSION_TOKEN
. The name will be
transformed to uppercase.
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
.