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

# orbies/aws-ecr

Build images and push them to the Amazon Elastic Container Registry.


## Commands

### build-and-push-image

Install AWS CLI, if needed, and configure. Log into Amazon ECR and push image to repository. Requires environment variables for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. We recommend these be saved in a Project (https://circleci.com/docs/2.0/env-vars/#setting-an-environment-variable-in-a-project) or in Contexts (https://circleci.com/docs/2.0/contexts).


| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `attach-workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace. Default is false.
 |
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_ACCESS_KEY.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_SECRET_ACCESS_KEY.
 |
| `checkout` | boolean | true | Boolean for whether or not to checkout as a first step. Default is true.
 |
| `create-repo` | boolean | false | Should the repo be created if it does not exist? |
| `docker-login` | boolean | false | Enable dockerhub authentication. Defaults to false.
 |
| `dockerfile` | string | Dockerfile | Name of dockerfile to use. Defaults to Dockerfile. |
| `dockerhub-password` | env_var_name | DOCKERHUB_PASSWORD | Dockerhub password to be configured. Set this to the name of the environment variable you will set to hold this value, i.e. DOCKERHUB_PASSWORD.
 |
| `dockerhub-username` | env_var_name | DOCKERHUB_USERNAME | Dockerhub username to be configured. Set this to the name of the environment variable you will set to hold this value, i.e. DOCKERHUB_USERNAME.
 |
| `executor` | executor | default | executor to use for this job |
| `extra-build-args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build
 |
| `no-output-timeout` | string | 10m | The amount of time to allow the docker build command to run before timing out (default is `10m`)
 |
| `path` | string | . | Path to the directory containing your Dockerfile and build context. Defaults to . (working directory). |
| `profile-name` | string | default | AWS profile name to be configured. |
| `region` | env_var_name | AWS_REGION | Name of env var storing your AWS region information, defaults to AWS_REGION
 |
| `remote-docker-layer-caching` | boolean | false | Enable Docker layer caching if using remote Docker engine. Defaults to false.
 |
| `remote-docker-version` | string | 19.03.13 | Specific remote docker version |
| `repo` | string |  | Name of an Amazon ECR repository |
| `repo-scan-on-push` | boolean | true | Should the created repo be security scanned on push? |
| `setup-remote-docker` | boolean | false | Setup and use CircleCI's remote Docker environment for Docker and docker-compose commands? Not required if using the default executor
 |
| `skip-when-tags-exist` | boolean | false | Whether to skip image building if all specified tags already exist in ECR |
| `tag` | string | latest | A comma-separated string containing docker image tags to build and push (default = latest) |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory)
 |

### build-image

Build a docker image

| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | The Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com
 |
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_ACCESS_KEY.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_SECRET_ACCESS_KEY.
 |
| `checkout` | boolean | false | Boolean for whether or not to checkout as a first step. Default is false.
 |
| `dockerfile` | string | Dockerfile | Name of dockerfile to use. Defaults to Dockerfile. |
| `ecr-login` | boolean | false | Boolean for whether or not to log in to ECR before building. Default is false.
 |
| `extra-build-args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build
 |
| `no-output-timeout` | string | 10m | The amount of time to allow the docker command to run before timing out. |
| `path` | string | . | Path to the directory containing your Dockerfile and build context. Defaults to . (working directory). |
| `profile-name` | string | default | AWS profile name to be configured. Only required when skip-when-tags-exist or ecr-login are set to true.
 |
| `region` | env_var_name | AWS_REGION | Name of env var storing your AWS region information, defaults to AWS_REGION. Only required when skip-when-tags-exist or ecr-login are set to true.
 |
| `repo` | string |  | Name of an Amazon ECR repository |
| `skip-when-tags-exist` | boolean | false | Whether to skip image building if all specified tags already exist in ECR |
| `tag` | string | latest | A comma-separated string containing docker image tags (default = latest) |

### docker-ecr-login

Authenticate docker into the Amazon ECR service

| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_ACCESS_KEY.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_SECRET_ACCESS_KEY.
 |
| `profile-name` | string | default | AWS profile name to be configured. defaults to "default"
 |
| `region` | env_var_name | AWS_REGION | Name of env var storing your AWS region information, defaults to AWS_REGION
 |

### helm-ecr-login

Authenticate helm into the Amazon ECR service

| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_ACCESS_KEY.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_SECRET_ACCESS_KEY.
 |
| `helm-version` | string | v3.2.4 | Helm version to install, .e.g. v3.2.4.
 |
| `profile-name` | string | default | AWS profile name to be configured. defaults to "default"
 |
| `region` | env_var_name | AWS_REGION | Name of env var storing your AWS region information, defaults to AWS_REGION
 |

### login-and-push-helm-chart

Install AWS CLI and Helm, if needed, and configure. Log into Amazon ECR and push Helm chart to repository. Requires environment variables for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. We recommend these be saved in a Project (https://circleci.com/docs/2.0/env-vars/#setting-an-environment-variable-in-a-project) or in Contexts (https://circleci.com/docs/2.0/contexts).


| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `attach-workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace. Default is false.
 |
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_ACCESS_KEY.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_SECRET_ACCESS_KEY.
 |
| `checkout` | boolean | true | Boolean for whether or not to checkout as a first step. Default is true.
 |
| `create-repo` | boolean | false | Should the repo be created if it does not exist? |
| `executor` | executor | default | executor to use for this job |
| `path` | string | . | Path to the directory containing your Helm chart and build context. Defaults to . (working directory). |
| `profile-name` | string | default | AWS profile name to be configured. |
| `region` | env_var_name | AWS_REGION | Name of env var storing your AWS region information, defaults to AWS_REGION
 |
| `repo` | string |  | Name of an Amazon ECR repository |
| `repo-scan-on-push` | boolean | true | Should the created repo be security scanned on push? |
| `tag` | string | latest | A string containing the Helm chart tag to push (default = latest) |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory)
 |

### push-helm-chart

Push a helm chart to the Amazon ECR registry

| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `helm-version` | string | v3.2.4 | Helm version to install, .e.g. v3.2.4. |
| `path` | string | . | Path to the directory containing your Helm chart and build context. Defaults to . (working directory). |
| `repo` | string |  | Name of an Amazon ECR repository |
| `tag` | string | latest | A string containing the Helm chart tag to push (default = latest) |

### push-image

Push a container image to the Amazon ECR registry

| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `repo` | string |  | Name of an Amazon ECR repository |
| `tag` | string | latest | A comma-separated string containing docker image tags (default = latest) |

## Jobs

### build-and-push-image

Install AWS CLI, if needed, and configure. Log into Amazon ECR and push image to repository. Requires environment variables for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. We recommend these be saved in a Project (https://circleci.com/docs/2.0/env-vars/#setting-an-environment-variable-in-a-project) or in Contexts (https://circleci.com/docs/2.0/contexts).


| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `attach-workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace. Default is false.
 |
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_ACCESS_KEY_ID.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_SECRET_ACCESS_KEY.
 |
| `checkout` | boolean | true | Boolean for whether or not to checkout as a first step. Default is true.
 |
| `create-repo` | boolean | false | Should the repo be created if it does not exist? |
| `docker-login` | boolean | false | Enable dockerhub authentication. Defaults to false.
 |
| `dockerfile` | string | Dockerfile | Name of dockerfile to use. Defaults to Dockerfile. |
| `dockerhub-password` | env_var_name | DOCKERHUB_PASSWORD | Dockerhub password to be configured. Set this to the name of the environment variable you will set to hold this value, i.e. DOCKERHUB_PASSWORD.
 |
| `dockerhub-username` | env_var_name | DOCKERHUB_USERNAME | Dockerhub username to be configured. Set this to the name of the environment variable you will set to hold this value, i.e. DOCKERHUB_USERNAME.
 |
| `executor` | executor | default | executor to use for this job |
| `extra-build-args` | string |  | Extra flags to pass to docker build. For examples, see https://docs.docker.com/engine/reference/commandline/build
 |
| `no-output-timeout` | string | 10m | The amount of time to allow the docker build command to run before timing out. Defaults to '10m'
 |
| `path` | string | . | Path to the directory containing your Dockerfile and build context. Defaults to . (working directory). |
| `profile-name` | string | default | AWS profile name to be configured. |
| `region` | env_var_name | AWS_REGION | Name of env var storing your AWS region information, defaults to AWS_REGION
 |
| `remote-docker-layer-caching` | boolean | false | Enable Docker layer caching if using remote Docker engine. Defaults to false.
 |
| `remote-docker-version` | string | 19.03.13 | Specific remote docker version |
| `repo` | string |  | Name of an Amazon ECR repository |
| `setup-remote-docker` | boolean | false | Setup and use CircleCI's remote Docker environment for Docker and docker-compose commands? Not required if using the default executor
 |
| `skip-when-tags-exist` | boolean | false | Whether to skip image building if all specified tags already exist in ECR |
| `tag` | string | latest | A comma-separated string containing docker image tags to build and push (default = latest) |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory)
 |

### push-helm-chart

Install AWS CLI and Helm, if needed, and configure. Log into Amazon ECR and push helm chart to repository. Requires environment variables for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. We recommend these be saved in a Project (https://circleci.com/docs/2.0/env-vars/#setting-an-environment-variable-in-a-project) or in Contexts (https://circleci.com/docs/2.0/contexts).


| Parameter | Type | Default | Description |
|---|---|---|---|
| `account-url` | env_var_name | AWS_ECR_ACCOUNT_URL | Env var storing Amazon ECR account URL that maps to an AWS account, e.g. {awsAccountNum}.dkr.ecr.us-west-2.amazonaws.com defaults to AWS_ECR_ACCOUNT_URL
 |
| `attach-workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace. Default is false.
 |
| `aws-access-key-id` | env_var_name | AWS_ACCESS_KEY_ID | AWS access key id for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_ACCESS_KEY_ID.
 |
| `aws-secret-access-key` | env_var_name | AWS_SECRET_ACCESS_KEY | AWS secret key for IAM role. Set this to the name of the environment variable you will set to hold this value, i.e. AWS_SECRET_ACCESS_KEY.
 |
| `checkout` | boolean | true | Boolean for whether or not to checkout as a first step. Default is true.
 |
| `create-repo` | boolean | false | Should the repo be created if it does not exist? |
| `executor` | executor | default | executor to use for this job |
| `path` | string | . | Path to the directory containing your Chart and build context. Defaults to . (working directory). |
| `profile-name` | string | default | AWS profile name to be configured. |
| `region` | env_var_name | AWS_REGION | Name of env var storing your AWS region information, defaults to AWS_REGION
 |
| `repo` | string |  | Name of an Amazon ECR repository |
| `tag` | string | latest | A string containing helm chart tag to push (default = latest) |
| `workspace-root` | string | . | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '.' (the working directory)
 |

## Executors

### default

CircleCI's Ubuntu-based machine executor VM: https://circleci.com/docs/2.0/executor-types/#using-machine


| Parameter | Type | Default | Description |
|---|---|---|---|
| `image` | string | ubuntu-2004:202010-01 |  |
| `use-docker-layer-caching` | boolean | false |  |

## Examples

### simple-build-and-push

Log into AWS, build and push image to Amazon ECR

```yaml
orbs:
  aws-ecr: circleci/aws-ecr@x.y.z
version: 2.1
workflows:
  build_and_push_image:
    jobs:
      - aws-ecr/build-and-push-image:
          account-url: AWS_ECR_ACCOUNT_URL_ENV_VAR_NAME
          aws-access-key-id: ACCESS_KEY_ID_ENV_VAR_NAME
          aws-secret-access-key: SECRET_ACCESS_KEY_ENV_VAR_NAME
          context: myContext
          create-repo: true
          dockerfile: myDockerfile
          no-output-timeout: 20m
          path: pathToMyDockerfile
          profile-name: myProfileName
          region: AWS_REGION_ENV_VAR_NAME
          repo: myECRRepository
          skip-when-tags-exist: false
          tag: latest,myECRRepoTag
```

### simple-push-helm-chart

Log into AWS and push Helm Chart to Amazon ECR

```yaml
orbs:
  aws-ecr: circleci/aws-ecr@x.y.z
version: 2.1
workflows:
  build_and_push_image:
    jobs:
      - aws-ecr/build-and-push-image:
          account-url: AWS_ECR_ACCOUNT_URL_ENV_VAR_NAME
          aws-access-key-id: ACCESS_KEY_ID_ENV_VAR_NAME
          aws-secret-access-key: SECRET_ACCESS_KEY_ENV_VAR_NAME
          context: myContext
          create-repo: true
          path: pathToMyHelmChart
          profile-name: myProfileName
          region: AWS_REGION_ENV_VAR_NAME
          repo: myECRRepository
          tag: 1.0.0
```