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

# circleci/aws-elastic-beanstalk

Deploy and scale web applications and services via AWS Elastic Beanstalk with CircleCI.


## Commands

### setup

Install and authenticate with the Elastic Beanstalk CLI. You must have your AWS auth environment variables set for ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_DEFAULT_REGION"].


| Parameter | Type | Default | Description |
|---|---|---|---|
| `version` | string |  | The version of the Elastic Beanstalk CLI that you wish to install. Defaults to latest. |

## Jobs

### deploy

Deploy an update to an existing AWS Elastic Beanstalk environment.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `app_dir` | string | . | Path to the directory containing your application source code. My default, the current directory will be used. |
| `application_name` | string |  | The name of the application (used during `eb init`). |
| `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.
 |
| `deploy_markers_component_name` | string |  | Component name shown in the CircleCI Deploys UI. Used by LOG, PLAN, and PLAN_AND_UPDATE modes. When left empty, falls back to the application_name parameter.
 |
| `deploy_markers_deploy_name` | string | ${CIRCLE_WORKFLOW_JOB_ID} | Unique identifier for this deployment within the workflow. Used by PLAN and PLAN_AND_UPDATE modes. Must be unique if planning multiple deployments in the same workflow. Defaults to the CircleCI workflow job ID.
 |
| `deploy_markers_environment_name` | string | default | Environment name shown in the CircleCI Deploys UI. Used by LOG, PLAN, and PLAN_AND_UPDATE modes. Defaults to 'default'.
 |
| `deploy_markers_mode` | enum | PLAN_AND_UPDATE | Controls CircleCI deploy marker integration via the deploys orb. OFF: no deploy markers are created. LOG: logs a deployment event after the EB deploy completes. PLAN: creates a planned deployment marker before the EB deploy; status updates are left to the caller. PLAN_AND_UPDATE: full lifecycle — plan before deploy, mark as running, then set SUCCESS or FAILED after (default).
 |
| `deploy_markers_namespace` | string |  | Namespace of the deployment shown in the CircleCI Deploys UI. Used by LOG, PLAN, and PLAN_AND_UPDATE modes. When left empty, the deploys orb uses 'default'.
 |
| `deploy_markers_target_version` | string |  | Version identifier shown in the CircleCI Deploys UI. Used by LOG, PLAN, and PLAN_AND_UPDATE modes. When left empty, the deploys orb uses the short commit SHA.
 |
| `description` | string |  | The description for the application version, enclosed in double quotation marks. |
| `environment_name` | string |  | The name of the existing environment (created with `eb create`) to update. |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `label` | string |  | Specify a label to use for the version that the EB CLI creates. If the label has already been used, the EB CLI redeploys the previous version with that label. |
| `platform_version` | string | node.js 22 | The platform version to use. You can specify a platform, a platform and version, a platform branch, a solution stack name, or a solution stack ARN. Use 'eb platform list' to get a list of available configurations. |
| `profile_name` | string | default | The name of an AWS profile to use with aws-cli commands |
| `region` | string | ${AWS_DEFAULT_REGION} | AWS region to deploy app. Defaults to environment variable ${AWS_DEFAULT_REGION}.
 |

## Executors

### default

A Docker image created by CircleCI with continuous delivery and deployment pipelines in mind. It contains the AWS CLI and other related tools.


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

## Examples

### deploy_eb_application_to_env_with_oidc

Easily deploy your application to Elastic Beanstalk with the provided deploy job using OIDC for authentication.
Import the aws-cli orb and authenticate using the aws-cli/setup command with a valid role_arn for OIDC authentication.
This example shows how a Node.JS application may be tested and then deployed in a realistic CI environment, using both the Node orb and AWS Elastic Beanstalk orb.
This assumes the EB environment already exists and is awaiting deployments.
Deploy markers are enabled by default (PLAN_AND_UPDATE mode): a CircleCI deploy marker is created before the deploy,
marked as running when it starts, and automatically updated to success or failed when the job completes.
The target version defaults to the short commit SHA and is shown in the CircleCI Deploys UI.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@4.0
  eb: circleci/aws-elastic-beanstalk@3.0
  node: circleci/node@5.1.0
workflows:
  elastic-beanstalk-workflow:
    jobs:
      - node/test
      - eb/deploy:
          auth:
            - aws-cli/setup:
                profile: OIDC-USER
                role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_CODEDEPLOY_ROLE
          context: CircleCI_OIDC_Token
          environment_name: my-app
          filters:
            branches:
              only:
                - main
          label: version-<<pipeline.number>>
          profile: OIDC-USER
          requires:
            - node/test
```

### deploy_eb_with_deploy_markers

Deploy an Elastic Beanstalk application with CircleCI deploy markers (enabled by default via PLAN_AND_UPDATE mode). The default PLAN_AND_UPDATE lifecycle creates a planned marker before the deploy, marks it as running when the deploy starts, and automatically sets it to success or failed when the job completes — no extra configuration required.
This example shows the optional parameters available to customize deploy marker behavior:
  deploy_markers_target_version   - version label shown in the CircleCI Deploys UI (defaults to short commit SHA)
  deploy_markers_deploy_name      - unique identifier for this deployment; defaults to the workflow job ID,
                                    which is already unique per execution, but can be set explicitly
  deploy_markers_component_name   - component label shown in the CircleCI Deploys UI (defaults to application_name)
  deploy_markers_environment_name - environment label shown in the CircleCI Deploys UI (defaults to 'default')
  deploy_markers_mode             - override the default PLAN_AND_UPDATE mode when needed:
                                      LOG             - log a deployment event after the EB deploy (no planned marker)
                                      PLAN            - create a planned marker before deploy; caller manages status updates
                                      OFF             - disable deploy markers entirely


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.4
  aws-elastic-beanstalk: circleci/aws-elastic-beanstalk@2.0
workflows:
  deploy:
    jobs:
      - aws-elastic-beanstalk/deploy:
          application_name: my-app
          auth:
            - aws-cli/setup:
                role_arn: ${AWS_ROLE_ARN}
          environment_name: my-app-prod
          name: deploy-app
      - aws-elastic-beanstalk/deploy:
          application_name: my-app
          auth:
            - aws-cli/setup:
                role_arn: ${AWS_ROLE_ARN}
          deploy_markers_deploy_name: deploy-my-app-staging
          deploy_markers_target_version: ${CIRCLE_SHA1}
          environment_name: my-app-staging
          name: deploy-app-staging
      - aws-elastic-beanstalk/deploy:
          application_name: my-app
          auth:
            - aws-cli/setup:
                role_arn: ${AWS_ROLE_ARN}
          deploy_markers_deploy_name: deploy-my-app-prod
          deploy_markers_target_version: ${CIRCLE_SHA1}
          environment_name: my-app-prod
          name: deploy-app-prod
      - aws-elastic-beanstalk/deploy:
          application_name: my-app-v2-internal
          auth:
            - aws-cli/setup:
                role_arn: ${AWS_ROLE_ARN}
          deploy_markers_component_name: my-app
          deploy_markers_environment_name: production
          environment_name: my-app-v2-internal-prod-us-east-1
          name: deploy-custom-labels
      - aws-elastic-beanstalk/deploy:
          application_name: my-app
          auth:
            - aws-cli/setup:
                role_arn: ${AWS_ROLE_ARN}
          deploy_markers_mode: LOG
          environment_name: my-app-prod
          name: deploy-log
      - aws-elastic-beanstalk/deploy:
          application_name: my-app
          auth:
            - aws-cli/setup:
                role_arn: ${AWS_ROLE_ARN}
          deploy_markers_mode: 'OFF'
          environment_name: my-app-prod
          name: deploy-no-markers
```

### install_eb_cli

Easily install and utilize the AWS Elastic Beanstalk CLI within your CI pipelines.


```yaml
version: '2.1'
orbs:
  eb: circleci/aws-elastic-beanstalk@3.0
jobs:
  eb-demo:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - eb/setup
      - run:
          command: |
            eb create my-environment
            eb deploy my-environment
            eb status
          name: You may now use the EB CLI within this job
workflows:
  elastic-beanstalk-workflow:
    jobs:
      - eb-demo
```