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

      # 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}}/{{artifactFileName}}'

      # Custom download URL.
      # If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
      # environment variable may be defined.
      #   
      downloadUrl: 'https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFileName}}'

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

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

  # 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}}/{{artifactFileName}}"

  # Custom download URL.
  # If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
  # environment variable may be defined.
  #   
  downloadUrl = "https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFileName}}"

  # 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__"

  # 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.
        // Valid 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,

        // 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}}/{{artifactFileName}}",

        // Custom download URL.
        // If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
        // environment variable may be defined.
        //   
        "downloadUrl": "https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFileName}}",

        // 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__",

        // 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.
          Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
          Defaults to `ALWAYS`.
          
        -->
        <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>

        <!--
          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}}/{{artifactFileName}}</path>

        <!--
          Custom download URL.
          If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
          environment variable may be defined.
            
        -->
        <downloadUrl>https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFileName}}</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>

        <!--
          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.
        // Valid 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

        // 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}}/{{artifactFileName}}'

        // Custom download URL.
        // If left unspecified, the `JRELEASER_S3_${name}_DOWNLOAD_URL`
        // environment variable may be defined.
        //   
        downloadUrl = 'https://{{bucket}}.s3.{{region}}.amazonaws.com/{{projectName}}/{{tagName}}/{{artifactFileName}}'

        // 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__'

        // 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}}/{{artifactFileName}}'.

And will result in a final URL like https://s3.amazonaws.com/app/downloads/1.0.0/app-1.0.0.zip.

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.