# Create a repository

Create a private or public repository before you push to it, with tag immutability, a storage cap and tags set from the start.

A `docker push` to a name that has no repository yet creates one too (see
[Push an image](push-an-image.md)); creating it first lets you choose its settings. Replace
my-app with the repository name.

## Prerequisites

- Permission for `ecr:CreateRepository`. Without it the console's create page sends you back to
  the repository list.
- The organization is below its repository quota (see [Quotas](quotas.md)).

## Create the repository

**Console**
1. Open **Container registry**, then choose **Create image repository**.
2. For **Repository name**, enter my-app.
3. (Optional) For **Description**, enter a description.
4. Under **Who can pull**, choose **Private** (the default) or **Public**.
5. (Optional) Under **Project and tags**, set the repository's tags.
6. Choose **Create image repository**.

The console sets name, description, visibility and tags. Tag immutability and a storage cap are set
afterwards on the **Settings** tab, or here through the CLI, the API or Terraform.

**CLI**
```sh
dcloud ecr repositories create --name my-app --tag-mutability immutable \
  --tag-mutability-exclusions latest
```

**API**
```http
POST /ecr/api/repositories
{ "name": "my-app", "description": "Order service", "visibility": "private", "tagMutability": "immutable", "tagMutabilityExclusions": ["latest"] }
```

**Terraform**
```hcl
resource "dcloud_ecr_repository" "my_app" {
  name                      = "my-app"
  tag_mutability            = "immutable"
  tag_mutability_exclusions = ["latest"]
}
```

## Repository settings

| Field                     | Values                                                                            | Default   |
| ------------------------- | --------------------------------------------------------------------------------- | --------- |
| `name`                    | 2–255 characters; see [Repositories, tags and images](repositories-and-images.md) | required  |
| `description`             | up to 256 characters                                                              | none      |
| `visibility`              | `private`, `public`                                                               | `private` |
| `tagMutability`           | `mutable`, `immutable`                                                            | `mutable` |
| `tagMutabilityExclusions` | up to 10 tag patterns (`*` globs) that stay mutable                               | none      |
| `storageQuotaBytes`       | 1 MiB (1048576) to 1 PiB, or `null`                                               | no cap    |
| `tags`                    | key/value pairs                                                                   | none      |

The name cannot be changed later. In the console the description cannot be changed either; the API
(`PATCH /ecr/api/repositories/{id}` with `description`) can.

## Result

`201` with the repository, its `id` included. The console opens the repository's page. Creating a
repository costs nothing; you pay for the layers pushed into it.

## If it is refused

- `409` `A repository named "my-app" already exists`.
- `409` with code `QuotaExceeded` when the organization is at its repository quota; the message
  starts with "Quota exceeded:".
- `400` when a tag key your organization requires is missing, or when the project the repository
  is created in does not exist.

## Related

- [Make a repository public](make-a-repository-public.md)
- [Make tags immutable](make-tags-immutable.md)
- [Set a storage quota](set-a-storage-quota.md)
- `ecr.repositories.create` · `dcloud ecr repositories create` · `dcloud_ecr_repository`
