AWS S3

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

Prerequisites:

An AWS account with S3 access.

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

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