AWS S3

Uploads artifacts, files, and signatures to an AWS S3 bucket.

Prerequisites:
  • An AWS account with S3 access.

Configuration

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

# 
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.active

JRELEASER_UPLOAD_S3_${name}_ACTIVE
JRELEASER_UPLOAD_S3_ACTIVE

region

jreleaser.upload.s3.${name}.region
jreleaser.upload.s3.region
jreleaser.s3.${name}.region
jreleaser.s3.region

JRELEASER_UPLOAD_S3_${name}_REGION
JRELEASER_UPLOAD_S3_REGION
JRELEASER_S3_${name}_REGION
JRELEASER_S3_REGION

bucket

jreleaser.upload.s3.${name}.bucket
jreleaser.upload.s3.bucket
jreleaser.s3.${name}.bucket
jreleaser.s3.bucket

JRELEASER_UPLOAD_S3_${name}_BUCKET
JRELEASER_UPLOAD_S3_BUCKET
JRELEASER_S3_${name}_BUCKET
JRELEASER_S3_BUCKET

accessKeyId

jreleaser.upload.s3.${name}.access.key.id
jreleaser.upload.s3.access.key.id
jreleaser.s3.${name}.access.key.id
jreleaser.s3.access.key.id

JRELEASER_UPLOAD_S3_${name}_ACCESS_KEY_ID
JRELEASER_UPLOAD_S3_ACCESS_KEY_ID
JRELEASER_S3_${name}_ACCESS_KEY_ID
JRELEASER_S3_ACCESS_KEY_ID

secretKey

jreleaser.upload.s3.${name}.secret.key
jreleaser.upload.s3.secret.key
jreleaser.s3.${name}.secret.key
jreleaser.s3.secret.key

JRELEASER_UPLOAD_S3_${name}_SECRET_KEY
JRELEASER_UPLOAD_S3_SECRET_KEY
JRELEASER_S3_${name}_SECRET_KEY
JRELEASER_S3_SECRET_KEY

sessionToken

jreleaser.upload.s3.${name}.session.token
jreleaser.upload.s3.session.token
jreleaser.s3.${name}.session.token
jreleaser.s3.session.token

JRELEASER_UPLOAD_S3_${name}_SESSION_TOKEN
JRELEASER_UPLOAD_S3_SESSION_TOKEN
JRELEASER_S3_${name}_SESSION_TOKEN
JRELEASER_S3_SESSION_TOKEN

path

jreleaser.upload.s3.${name}.path
jreleaser.upload.s3.path
jreleaser.s3.${name}.path
jreleaser.s3.path

JRELEASER_UPLOAD_S3_${name}_PATH
JRELEASER_UPLOAD_S3_PATH
JRELEASER_S3_${name}_PATH
JRELEASER_S3_PATH

downloadUrl

jreleaser.upload.s3.${name}.download.url
jreleaser.upload.s3.download.url
jreleaser.s3.${name}.download.url
jreleaser.s3.download.url

JRELEASER_UPLOAD_S3_${name}_DOWNLOAD_URL
JRELEASER_UPLOAD_S3_DOWNLOAD_URL
JRELEASER_S3_${name}_DOWNLOAD_URL
JRELEASER_S3_DOWNLOAD_URL

endpoint

jreleaser.upload.s3.${name}.endpoint
jreleaser.upload.s3.endpoint
jreleaser.s3.${name}.endpoint
jreleaser.s3.endpoint

JRELEASER_UPLOAD_S3_${name}_ENDPOINT
JRELEASER_UPLOAD_S3_ENDPOINT
JRELEASER_S3_${name}_ENDPOINT
JRELEASER_S3_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

FOOBAR

fooBar

foobar

FOOBAR

foo bar

foo.bar

FOO_BAR

foo-bar

foo.bar

FOO_BAR

foo_bar

foo.bar

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 is skipUploadS3Foo.

  • if the name is fooBar the resulting property key is skipUploadS3FooBar.

  • if the name is foo-bar the resulting property key is skipUploadS3FooBar.