Deploy a Node.js App to AWS Elastic Beanstalk Using CircleCI Orbs

Problem: Repeating the same Elastic Beanstalk steps in every pipeline

When you maintain multiple Node.js services that ship to AWS Elastic Beanstalk, the CircleCI configuration tends to duplicate the same sequence: install dependencies, run tests, zip the source, invoke the EB CLI to create an application version, and update the environment. Copy‑pasting this logic leads to drift, makes version upgrades painful, and obscures the intent of each pipeline.

Thesis: The AWS Elastic Beanstalk orb provides a single, version‑controlled command that encapsulates those steps, letting you focus on application‑specific workflows while keeping the deploy process consistent and auditable.

1. Adding the orb to your config

First, declare the orb in the orbs: section of .circleci/config.yml. Pin to a specific minor or patch version to avoid surprise breaking changes when a new major release appears.

version: 2.1
orbs:
  aws-elastic-beanstalk: circleci/aws-elastic-beanstalk@3.4.0  # example pin

jobs:
  build-test-deploy:
    docker:
      - image: cimg/node:20.10.0
    steps:
      - checkout
      - restore_cache:
          keys:
            - node-v1-{{ checksum "package-lock.json" }}
      - run: npm ci
      - save_cache:
          paths:
            - ./node_modules
          key: node-v1-{{ checksum "package-lock.json" }}
      - run: npm test
      - aws-elastic-beanstalk/deploy:
          application-name: $EB_APP_NAME
          environment-name: $EB_ENV_NAME
          region: $AWS_DEFAULT_REGION
          version-label: "${CIRCLE_SHA1}"
          # optional: wait for environment to be ready
          wait: true
workflows:
  version: 2
  deploy:
    jobs:
      - build-test-deploy:
          filters:
            branches:
              only: main

The aws-elastic-beanstalk/deploy command expects the following environment variables to be set at the project level (or via a context):

• AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY – credentials with permission to create application versions and update environments.
• AWS_DEFAULT_REGION – the EB region, e.g., us-east-1.
• EB_APP_NAME – the Elastic Beanstalk application name.
• EB_ENV_NAME – the target environment (e.g., staging).

Because the orb wraps the EB CLI, you do not need to install awsebcli yourself; the orb’s executor provides it.

2. Worked example: caching node_modules and deploying

Consider a repository with a typical Node.js layout:

.
├── .circleci/config.yml
├── package.json
├── package-lock.json
└── src/

The snippet above shows a realistic flow:

1. Checkout the source.
2. Restore cache using a key derived from the lockfile; if unchanged, this skips a full npm ci.
3. Install dependencies with npm ci (fast, reproducible).
4. Save cache for subsequent runs.
5. Run tests – adjust to your test command.
6. Deploy via the orb, which internally runs:
1. eb init (if the application/environment is not yet configured).
2. eb deploy with the supplied version label (the commit SHA).
3. Optionally waits for the environment to turn green.

When a push to main triggers the workflow, the CircleCI UI will show a job named build-test-deploy. Inside the job log you should see steps like:

> Restoring cache... (hit)
> npm ci
> npm test
> aws-elastic-beanstalk/deploy: Starting EB CLI...
> aws-elastic-beanstalk/deploy: eb init ...
> aws-elastic-beanstalk/deploy: eb deploy ...
> aws-elastic-beanstalk/deploy: Environment update completed successfully.

Note: The exact log lines depend on the orb version; the above illustrates the expected sequence.

3. Trade‑offs and limitations

While the orb reduces boilerplate, consider these points:

• Version pinning – Orbs are immutable; a new major release may change the command signature or default behavior. Pin to a specific version (as shown) and test upgrades in a feature branch before merging to main.
• Custom platform hooks – If your EB environment relies on .ebextensions files or container commands that need additional tooling, the orb’s default eb deploy may not invoke them exactly as you expect. Review the orb’s source or run a manual eb deploy locally to confirm compatibility.
• Limited configurability – The orb exposes a set of parameters (application name, environment name, version label, wait flag, etc.). Advanced use cases such as deploying to multiple environments in parallel or using custom EB CLI profiles require wrapping the orb command in a custom job or using the command feature of the orb.

4. Actionable closing steps

1. Add the orb stanza to your .circleci/config.yml with a pinned version.
2. Create the required environment variables in the CircleCI project settings (or via a context).
3. Push a commit to a feature branch and watch the pipeline; verify the deploy step completes without errors.
4. After success, open the Elastic Beanstalk environment URL and confirm the Node.js version matches the artifact you built.
5. Once validated, merge to main and consider setting up a scheduled workflow to test version upgrades of the orb.

By treating the Elastic Beanstalk deploy as a reusable orb, you keep your CI configuration DRY, reduce the chance of human error, and make future updates to the deployment process a matter of changing a single version number.