> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/aws-s3

Integrate Amazon AWS S3 with your CircleCI CI/CD pipeline easily with the aws-s3 orb.


## Commands

### copy

Copies a local file or S3 object to another location locally or in S3. https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html


| Parameter | Type | Default | Description |
|---|---|---|---|
| `arguments` | string |  | If you wish to pass any additional arguments to the aws copy command (i.e. -sse) |
| `from` | string |  | A local file or source s3 object |
| `profile_name` | string |  | AWS profile name to be configured. |
| `role_arn` | string |  | The Amazon Resource Name (ARN) of the role that the caller is assuming.
Role ARN must be configured for web identity.
 |
| `to` | string |  | A local target or s3 destination |
| `when` | enum | on_success | Add the when attribute to a job step to override its default behavior
and selectively run or skip steps depending on the status of the job.
 |

### sync

Syncs directories and S3 prefixes. https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html


| Parameter | Type | Default | Description |
|---|---|---|---|
| `arguments` | string |  | Optional additional arguments to pass to the `aws sync` command (e.g., `--acl public-read`). Note: if passing a multi-line value to this parameter, include `\` characters after each line, so the Bash shell can correctly interpret the entire command.
 |
| `from` | string |  | A local *directory* path to sync with S3 |
| `profile_name` | string |  | AWS profile name to be configured. |
| `to` | string |  | A URI to an S3 bucket, i.e. 's3://the-name-my-bucket' |
| `when` | enum | on_success | Add the when attribute to a job step to override its default behavior
and selectively run or skip steps depending on the status of the job.
 |

## Jobs

### copy

A job that copies a local file or S3 object to another location locally or in S3. https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html


| Parameter | Type | Default | Description |
|---|---|---|---|
| `arguments` | string |  | If you wish to pass any additional arguments to the aws copy command (i.e. -sse) |
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
If not provided, authentication will be handled by the environment (e.g., IAM roles, environment variables).
 |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `from` | string |  | A local file or source s3 object |
| `profile_name` | string |  | AWS profile name to be configured. |
| `to` | string |  | A local target or s3 destination |
| `when` | enum | on_success | Add the when attribute to a job step to override its default behavior
and selectively run or skip steps depending on the status of the job.
 |

### sync

A job that syncs directories and S3 prefixes. https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html


| Parameter | Type | Default | Description |
|---|---|---|---|
| `arguments` | string |  | If you wish to pass any additional arguments to the aws copy command (i.e. -sse) |
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
If not provided, authentication will be handled by the environment (e.g., IAM roles, environment variables).
 |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `from` | string |  | A local file or source s3 object |
| `profile_name` | string |  | AWS profile name to be configured. |
| `to` | string |  | A local target or s3 destination |
| `when` | enum | on_success | Add the when attribute to a job step to override its default behavior
and selectively run or skip steps depending on the status of the job.
 |

## Executors

### default

An AWS Docker image built to run on CircleCI that contains the AWS CLI and related tools.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Configure the executor resource class |
| `tag` | string | 2026.04.1 | Select any of the available tags here: https://circleci.com/developer/images/image/cimg/aws.
 |

## Examples

### authentication_with_jobs

The S3 orb allows you to "sync" directories or "copy" files to an S3 bucket. The example below demonstrates how to use the "sync" and "copy" jobs. It also demonstrates the use of OIDC authentication in a job with the required "auth" parameter. The aws-cli orb must be imported and the aws-cli/setup command must be used with a valid AWS role_arn.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.1
  aws-s3: circleci/aws-s3@4.1
workflows:
  s3-example:
    jobs:
      - aws-s3/copy:
          auth:
            - aws-cli/setup:
                profile_name: OIDC-User
                role_arn: arn:aws:iam::123456789012/role/VALID-S3-ROLE
          from: PATH/TO/FILE
          profile_name: OIDC-User
          to: s3://my-s3-bucket-name
      - aws-s3/sync:
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012/role/VALID-S3-ROLE
          from: bucket
          to: s3://my-s3-bucket-name/prefix
```

### static_credentials

How to use the S3 orb with static credentials.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.1
  aws-s3: circleci/aws-s3@4.1
jobs:
  build:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run: mkdir bucket && echo "lorem ipsum" > bucket/build_asset.txt
      - aws-cli/install
      - aws-s3/sync:
          arguments: |
            --acl public-read \
            --cache-control "max-age=86400"
          from: bucket
          to: s3://my-s3-bucket-name/prefix
      - aws-s3/copy:
          arguments: '--dryrun'
          from: bucket/build_asset.txt
          to: s3://my-s3-bucket-name
workflows:
  s3-example:
    jobs:
      - build:
          context: AWS_CREDENTIALS
```

### sync_and_copy_with_oidc

The S3 orb allows you to "sync" directories or "copy" files to an S3 bucket. The example below shows a typical CircleCI job where a file "bucket/build_asset.txt" is created, followed by how we can both sync, and/or copy the file. It also demonstrates the use of OIDC authentication by importing the aws-cli orb and providing the aws-cli/setup command with a valid AWS role_arn and profile name. If a profile name is specified with authentication, it must be specified in the copy and sync commands.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.1
  aws-s3: circleci/aws-s3@4.1
jobs:
  sync_and_copy:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run: mkdir bucket && echo "lorem ipsum" > bucket/build_asset.txt
      - aws-cli/setup:
          profile_name: OIDC-User
          role_arn: arn:aws:iam::123456789012/role/VALID-S3-ROLE
      - aws-s3/sync:
          arguments: |
            --acl public-read \
            --cache-control "max-age=86400"
          from: bucket
          profile_name: OIDC-User
          to: s3://my-s3-bucket-name/prefix
      - aws-s3/copy:
          arguments: '--dryrun'
          from: bucket/build_asset.txt
          profile_name: OIDC-User
          to: s3://my-s3-bucket-name
workflows:
  s3-example:
    jobs:
      - sync_and_copy
```