# Create a repository

Create an empty Git repository in your organization, private or public.

A new repository belongs to your organization and is addressed as `<organization>/<repository>`.
Replace my-repo with the name you want: 1 to 100 letters, digits, dots, dashes and
underscores, starting with a letter or digit.

**Important:**
A repository cannot be renamed (in Terraform, changing `name` replaces it). Choose the name you
want to keep.

## Prerequisites

- Permission for `git:CreateRepository`.
- For a public repository, also `git:PublishRepository`. See
  [Public repositories](public-repositories.md).
- In the Deutsche Cloud Console, starter files need `git:PushRepository` (without it the repository is
  created empty), and protecting the default branch needs `git:ManageBranchProtection`.
- In the Deutsche Cloud Console, also `git:ListRepositories` to open **Git → Repositories** (without it the
  page shows only an access-denied notice).
- The organization is below its `git.repositories` quota (see [Quotas](quotas.md)).

## Create it

**Console**
1. Open **Git → Repositories**, then choose **New repository**.
2. On step **Identity**, under **Source**, choose **Start empty**.
3. Under **Basics**, for **Repository name**, enter my-repo. The clone URLs it will have
   are shown below the field.
4. (Optional) For **Description**, enter what lives in the repository.
5. Under **Visibility**, choose **Private** or **Public**, then choose **Continue**.
6. On step **Initialisation**, (optional) for **Default branch**, enter a name other than `main`.
7. (Optional) Under **Starter files**, select **Add a README**, and choose a **.gitignore** and a
   **Licence**. They are committed as "Initial commit". Choose **Continue**.
8. On step **Access**, (optional) select **Protect** _branch_ to protect the default branch, and
   under **Give someone access to this repository** choose a **Person** and what they may do.
9. Check the summary, then choose **Create repository**. The repository's page opens. If the
   starter commit, the protection or the grant did not go through, the repository still exists:
   the page names what failed and offers **Go to repository**.

**CLI**
```sh
dcloud git repositories create --name my-repo \
  --description "Order service" --visibility private
```

**API**
```http
POST /git/api/repositories
{ "name": "orders", "description": "Order service", "visibility": "private" }
```

**Terraform**
```hcl
resource "dcloud_git_repository" "this" {
  name           = "my-repo"
  description    = "Order service"
  visibility     = "private"
  default_branch = "main"
}
```

From the API, CLI and Terraform, `template` starts the repository from another one: one commit
with that repository's files and no history, on which CI runs. It names a repository id of your
organization (which needs `git:PullRepository` on it), or `org/name` of a public repository, and
optionally a `ref`.

## Result

The API answers 201 with the repository and its clone URLs. It is empty unless you added starter
files or a template; push to it from a machine that has the code.

The call is refused with:

- 409 `A repository named "<name>" already exists`.
- 409 with `code: QuotaExceeded` when the organization has used its `git.repositories` quota.
- 404 `Template not found`, or 409 `The template is empty`. If the template cannot be copied after
  the repository was created, 409 `Repository created, but not filled from the template: <reason>`:
  the repository exists, empty.
- 403 without `git:PublishRepository` for `visibility: public`.

## Related

- [Clone over HTTPS](clone-over-https.md)
- [Import a repository](import-a-repository.md)
- [Change repository settings](change-repository-settings.md)
- `git.repositories.create` · `dcloud git repositories create` · `dcloud_git_repository`
