# Change repository settings

Change a repository's description, visibility, default branch, merge methods, or archive it.

Only the fields you send change. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60`.

## Prerequisites

- Permission for `git:UpdateRepository` on the repository. Without it the console shows the
  settings read-only and names the missing permission.
- To make a repository public that is not public yet, also `git:PublishRepository`.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's settings (without it the
  page is not found).

## Repository fields

| Field                        | Values                                                                                                | Default      |
| ---------------------------- | ----------------------------------------------------------------------------------------------------- | ------------ |
| `name`                       | the repository name; set at creation, cannot be changed                                               | required     |
| `description`                | text, up to 500 characters                                                                            | none         |
| `homepage`                   | an http or https link of up to 300 characters, shown as the About link; `null` removes it             | none         |
| `topics`                     | up to 20, each lowercase letters, digits and hyphens, up to 50 characters                             | none         |
| `visibility`                 | `private` or `public`; `internal` is a legacy value that is enforced exactly like `private`           | `private`    |
| `defaultBranch`              | a branch name, up to 100 characters                                                                   | `main`       |
| `isArchived`                 | boolean; an archived repository is read-only                                                          | `false`      |
| `allowMergeCommit`           | pull requests may merge with a merge commit                                                           | `true`       |
| `allowSquashMerge`           | pull requests may be squash-merged                                                                    | `true`       |
| `allowRebaseMerge`           | pull requests may be rebase-merged                                                                    | `true`       |
| `deleteBranchOnMerge`        | delete the source branch after a pull request merges                                                  | `false`      |
| `defaultWorkflowPermissions` | what a workflow job's token may do when its file sets no `permissions:`: `restricted` or `permissive` | `restricted` |

At least one merge method stays allowed: a change that would turn off the last one is refused with
400 `At least one merge method must stay allowed`. A merge with a method that is not allowed is
refused with 409 `This repository does not allow <method>; use <methods>.` With
`deleteBranchOnMerge`, the default branch, a branch that another open pull request merges into,
and one that branch protection keeps are not deleted.

An archived repository refuses pushes (over HTTPS and SSH), merges, changes to pull requests and
issues, and releases; the API answers 409 `Repository is archived`. Clones and reads keep working,
and its settings can still be changed, which is how it is unarchived.

On a mirror, the website and topics follow the source repository.

## Change them

**Console**
1. In the repository, choose **Settings**. **General** opens.
2. Under **Identity**, change **Description**, **Website** or **Topics** (separated by spaces).
   **Repository name** cannot be changed.
3. Under **Visibility**, choose **Private (only people given access)** or **Public (anyone can
   clone it without credentials)**.
4. Under **Default branch**, choose one of the repository's branches.
5. Under **Pull requests**, select or clear **Allow merge commits**, **Allow squash merging** and
   **Allow rebase merging** (the last one allowed cannot be cleared), and **Delete the branch after
   merging**.
6. Choose **Save changes**.
7. To archive, choose **Danger zone**, then **Archive** under **Archive this repository**, and
   confirm with **Archive repository**. **Unarchive** under **Unarchive this repository** undoes
   it.

**CLI**
```sh
dcloud git repositories update 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --default-branch main --delete-branch-on-merge
```

**API**
```http
PATCH /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60
{ "allowMergeCommit": false, "allowSquashMerge": true, "deleteBranchOnMerge": true }
```

**Terraform**
```hcl
resource "dcloud_git_repository" "this" {
  name                   = "my-repo"
  allow_merge_commit     = false
  allow_squash_merge     = true
  delete_branch_on_merge = true
}
```

## Result

The console shows **Settings saved**, and the repository's **Settings** page shows the new values.

## Delete a repository

**Warning:**
Deleting a repository deletes all its code, commits, branches, tags and history. It cannot be
undone. A fork of it stays, no longer linked to it.

Choose **Settings → Danger zone**, then **Delete repository** under **Delete this repository**.
Type the repository's name to confirm, and choose **Delete repository**. Or run
`dcloud git repositories delete`. Deleting needs `git:DeleteRepository`, a permission of its own.

## Related

- [Public repositories](public-repositories.md)
- [Merge a pull request](merge-a-pull-request.md)
- `git.repositories.update` · `dcloud git repositories update` · `dcloud_git_repository`
