# Add a deploy key

Give a machine SSH access to one repository, read-only unless you say otherwise.

A deploy key is an SSH public key that grants a machine access to one repository, and to no other.
It holds no IAM policies: a read-only key can clone and fetch, a read-write key can also push. The
machine clones with the repository's SSH URL, username `git`. The examples use the repository id
`5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60`; replace build-server with a name for the key.

## Prerequisites

- The machine's public key, made for this machine. A public key can be registered only once on the
  platform, and a key that is also registered as a person's account SSH key signs in as that person,
  not as the deploy key.
- Permission for `git:CreateDeployKey` on the repository (`git:GetRepository` to open its
  settings in the console). Without it, **Add key** stays visible and says which permission is
  missing.
- Room in the **Deploy keys per repository** quota.

## Add the key

**Console**
1. In the repository, choose **Settings**, then **Deploy keys**.
2. Choose **Add key**. The **New deploy key** form opens.
3. For **Key name**, enter build-server.
4. For **Public key**, paste the machine's public key.
5. Under **What it may do**, leave **Read-only access** selected. Clear it only for a machine that
   must push.
6. Choose **Add key**. The key is listed with its **Fingerprint** and its **Access**
   (**Read-only** or **Read-write**).

**CLI**
```sh
dcloud git deploy-keys create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --name build-server --public-key "$(cat build_server.pub)" --read-only
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/deploy-keys
{ "name": "build-server", "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEXAMPLE build", "readOnly": true }
```

**Terraform**
```hcl
resource "dcloud_git_deploy_key" "build" {
  repository_id = dcloud_git_repository.this.id
  name          = "build-server"
  public_key    = file("${path.module}/build_server.pub")
  read_only     = true
}
```

`readOnly` defaults to `true` in the API too; send `false` for a key that must push.

## Result

The machine can clone and fetch the repository over SSH, and push to it if the key is read-write.
A push with a read-only key is refused with
`This deploy key is read-only: it can clone and fetch this repository but not push to it.` A
deploy key can never push a protected tag, because it cannot hold `git:PushProtectedTag`.

A public key that cannot be parsed is refused with 400 `Not a valid SSH public key`.

## Remove the key

Choose **Delete** on the key's row, then **Delete key**. Any machine using it loses access. This
needs `git:DeleteDeployKey`; the CLI is `dcloud git deploy-keys delete`.

## Related

- [Clone over SSH](clone-over-ssh.md)
- `git.deploy-keys.create` · `dcloud git deploy-keys create` · `dcloud_git_deploy_key`
