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

# circleci/aws-lambda

Deploy and manage AWS Lambda functions via CircleCI. Uploads your deployment package to S3 using the aws-s3 orb, then triggers a Lambda function code update via the AWS CLI. Supports both static IAM credentials and OIDC-based role assumption.


## Jobs

### update_lambda_function

Uploads a deployment ZIP to S3 using the aws-s3 orb, then calls `aws lambda update-function-code` to deploy the new code to a Lambda function. Authentication is handled by the caller via the `auth` steps parameter — pass `aws-cli/setup` with your preferred method (OIDC, static keys, etc.), or omit it entirely if credentials are already present in the environment. Optionally emits CircleCI deploy markers via the deploys orb.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | Authentication steps used to configure AWS credentials before the deploy. Import the aws-cli orb and provide aws-cli/setup with your preferred method (OIDC role assumption, static keys, etc.). If omitted, the job will rely on credentials already present in the environment (e.g. an IAM instance profile or environment variables set in a prior step or context).
 |
| `checkout` | boolean | true | Whether to check out source code at the start of the job. Set to false when using `attach_workspace` in pre-steps to bring in a pre-built artifact.
 |
| `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 workflow job ID, which is unique per job execution across all concurrent runs.
 |
| `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 Lambda deploy completes. PLAN: creates a planned deployment marker before the Lambda 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_target_version` | string |  | Version identifier shown in the CircleCI Deploys UI. Used by LOG, PLAN, and PLAN_AND_UPDATE modes. If not set, the Deploys Orb defaults to the short commit SHA.
 |
| `function_name` | string |  | The name, ARN, or partial ARN of the Lambda function to update (e.g. my-function or arn:aws:lambda:us-east-1:123456789012:function:my-function).
 |
| `publish` | boolean | false | When true, publishes a new numbered Lambda version after the code update. Equivalent to passing --publish to `aws lambda update-function-code`.
 |
| `qualifier` | string |  | Lambda function version or alias qualifier. Maps to --qualifier in `aws lambda update-function-code`. Leave empty to update $LATEST.
 |
| `s3_bucket` | string |  | Name of the S3 bucket that will hold the deployment package. |
| `s3_copy_arguments` | string |  | Additional arguments forwarded to `aws s3 cp` (e.g. --sse aws:kms).
 |
| `s3_key` | string |  | S3 object key for the deployment package (e.g. my-function/v1.0.0.zip).
 |
| `source_zip_file` | string | function.zip | Local path to the deployment ZIP file to upload to S3. |

## Executors

### default

A cimg/base Docker image. Install the AWS CLI via the auth parameter of the update_lambda_function job (e.g. using aws-cli/setup).


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | current | Pick a specific cimg/base image tag: https://hub.docker.com/r/cimg/base/tags
 |

## Examples

### update_function

Deploy a Lambda function using OIDC authentication via the auth steps parameter.
Deploy markers are enabled by default in PLAN_AND_UPDATE mode: a marker is created before the deploy, set to RUNNING when it starts, then automatically resolved to SUCCESS or FAILED. The deploy will appear in the CircleCI Deploys UI without any extra configuration.
The deploy_markers_mode parameter controls this behaviour:
  PLAN_AND_UPDATE (default) — full lifecycle tracking in the Deploys UI.
  LOG                       — logs a single event after a successful deploy.
  PLAN                      — creates a marker before the deploy; status
                              updates are left to the caller.
  OFF                       — disables deploy markers entirely (e.g. for
                              non-production environments).


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.1
  aws-lambda: circleci/aws-lambda@1.0.0
workflows:
  deploy-lambda:
    jobs:
      - aws-lambda/update_lambda_function:
          auth:
            - aws-cli/setup:
                region: us-east-1
                role_arn: arn:aws:iam::123456789012:role/my-circleci-deploy-role
          function_name: my-lambda-function
          name: deploy-production
          publish: true
          s3_bucket: my-deployment-bucket
          s3_key: my-function/<< pipeline.git.tag >>.zip
          source_zip_file: build/my-function.zip
      - aws-lambda/update_lambda_function:
          auth:
            - aws-cli/setup:
                region: us-east-1
                role_arn: arn:aws:iam::123456789012:role/my-circleci-deploy-role
          deploy_markers_mode: LOG
          function_name: my-lambda-function-staging
          name: deploy-staging
          s3_bucket: my-deployment-bucket
          s3_key: my-function/<< pipeline.git.tag >>.zip
          source_zip_file: build/my-function.zip
      - aws-lambda/update_lambda_function:
          auth:
            - aws-cli/setup:
                region: us-east-1
                role_arn: arn:aws:iam::123456789012:role/my-circleci-deploy-role
          deploy_markers_deploy_name: my-lambda-deploy
          deploy_markers_mode: PLAN
          function_name: my-lambda-function
          name: deploy-with-custom-marker
          s3_bucket: my-deployment-bucket
          s3_key: my-function/<< pipeline.git.tag >>.zip
          source_zip_file: build/my-function.zip
      - aws-lambda/update_lambda_function:
          auth:
            - aws-cli/setup:
                region: us-east-1
                role_arn: arn:aws:iam::123456789012:role/my-circleci-deploy-role
          deploy_markers_mode: 'OFF'
          function_name: my-lambda-function-dev
          name: deploy-dev
          s3_bucket: my-deployment-bucket
          s3_key: my-function/<< pipeline.git.tag >>.zip
          source_zip_file: build/my-function.zip
```