# Clone over HTTPS

Create an access token and use it to clone, fetch and push over HTTPS.

An access token is the credential for HTTPS. It is shown once when created, may expire, and
records when it was last used (`lastUsedAt`). Replace my-org and my-repo with your
organization's and repository's names.

## Credentials at a glance

| Credential      | Where               | Username         | Password         | Expiry                                              |
| --------------- | ------------------- | ---------------- | ---------------- | --------------------------------------------------- |
| Access token    | HTTPS               | the token prefix | the token secret | optional, set at creation; `lastUsedAt` is recorded |
| Account SSH key | SSH                 | `git`            | none             | none                                                |
| Deploy key      | SSH, one repository | `git`            | none             | none; read-only by default                          |

## Prerequisites

- Permission for `git:CreateAccessToken`.
- `git:PullRepository` to clone, and `git:PushRepository` to push.
- In the Deutsche Cloud Console, also `git:GetRepository` to open the repository's settings (without it the
  page is not found).

## Create a token

A token can be narrowed when it is made: to **some repositories** (`repositoryIds`; on a
repository's **Settings → Access tokens** page it starts limited to that repository) and to
**read only** (`access: "read"`: clone, fetch and the API's reads, no push or writes). It never does
more than its owner's own policies allow.

**Console**
1. In a repository, choose **Settings**, then **Access tokens**.
2. Choose **Create token**.
3. For **Name**, enter laptop.
4. For **Expires**, choose **In 7 days**, **In 30 days** (the console's default), **In 90 days**,
   **In a year** or **Never**.
5. Under **Access**, for **Repositories**, keep **Only** _this repository_ (the default) or choose
   **Every repository you can reach**. For **Permissions**, keep **Read and write (clone, fetch and
   push)** or choose **Read only (clone and fetch, no push)**.
6. Choose **Create token**, and copy the token: it is shown once, with a clone URL that has it
   embedded.

**CLI**
```sh
dcloud git access-tokens create --name laptop --expires-in-days 30 --access read
```

**API**
```http
POST /git/api/access-tokens
{ "name": "laptop", "expiresInDays": 30, "access": "read", "repositoryIds": ["5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60"] }
```

The API and CLI defaults differ from the console's: without `expiresInDays` the token never
expires, without `access` it can write, and without `repositoryIds` it reaches every repository you
can. `expiresInDays` is 1 to 365. A `repositoryIds` entry that is not a repository of your
organization is refused with 422 `No such repository: <id>`. Tokens count against the
**Access tokens** quota.

## Clone and push

```sh
git clone https://git.<platform domain>/my-org/my-repo.git
```

When asked, give the token's prefix as the username and its secret as the password. Pasting the
whole `prefix.secret` value into either field also works.

## Result

The repository is cloned, and `git push` works with the same credentials when the token and your
policies allow it.

## Revoke a token

Under a repository's **Settings → Access tokens**, open the token's actions menu, choose **Revoke
token**, then confirm with **Revoke token**. Under **Account → Git tokens**, which lists your tokens
from every repository, choose **Revoke** on its row and confirm with **Revoke**. Or run
`dcloud git access-tokens delete`. Revoking needs `git:DeleteAccessToken`; the token stops working at
once.

## Related

- [Clone over SSH](clone-over-ssh.md)
- [Add a deploy key](add-a-deploy-key.md)
- `git.access-tokens.create` · `dcloud git access-tokens create`
