# DigitalOcean setup

> Connect your DigitalOcean team to Manage Runners or create an API token with custom scopes, and learn what Manage Runners creates in your account, how SSH keys, labels and outbound traffic work, and what DigitalOcean bills.

Source: https://managerunners.com/docs/manual/digitalocean/

Your runners can also be droplets in your own DigitalOcean account. Manage Runners manages them through the DigitalOcean API, and DigitalOcean bills the droplets to your team. Hetzner Cloud stays the default; you choose the provider when you create a runner. For Hetzner, see [Hetzner setup](https://managerunners.com/docs/manual/hetzner/).

There are two ways to give Manage Runners access: [connect your DigitalOcean team](#connect-digitalocean) once for your organization, which we recommend, or [create an API token](#create-an-api-token) and paste it for each runner.

We recommend a separate DigitalOcean team that only contains your runners. Runners are created in and billed to the team you connect or the token belongs to, so a separate team keeps them apart from your other droplets and reserved IPs. To create a team, click your profile icon in the top right of the control panel and select **Create a Team**. A new team uses your default team's payment method, if it has one. To work in another team, select **Switch Teams** in the same menu.

## Connect DigitalOcean

1. In the dashboard, select **Create Runner** and choose **DigitalOcean** under **Cloud provider**.
2. Under **DigitalOcean access**, select **Connect DigitalOcean**. DigitalOcean opens in the same tab; sign in if asked.
3. Choose the team for your runners and select **Authorize application**. DigitalOcean shows the permissions Manage Runners asks for: the scopes in the [table below](#create-an-api-token) and, to show only the sizes your team may create, `sizes:read` and `regions:read`.
4. DigitalOcean returns you to the dashboard, which shows **Team** with the team's name. The form keeps what you had entered.

Owners and editors can connect teams; viewers see the connections. The connection belongs to your organization, so everyone in it can use it for runners and autoscaling. Each team is connected once; **Connect another team** adds a second one, and when you create a runner you choose the team. You can also connect teams under **Organization settings** > **DigitalOcean connections**, where the list shows each team, who connected it, since when, and its status.

Manage Runners keeps the connection's access and renews it on its own; nobody needs to copy a token. If DigitalOcean no longer accepts it, for example because the app was removed from the team under **Settings** > **Applications & API** > **Authorized applications**, the connection is marked **Reconnect needed** and its runners become **Unknown** at their next change, like runners whose token stopped working. Select **Reconnect** and authorize the same team again: the runners that use the connection are checked again on their own and return to their state. Until then, new runners and autoscaling cannot use it.

**Disconnect** in the list revokes Manage Runners' access at DigitalOcean. It is refused while runners or autoscaling policies use the connection; the message names them. Delete them or switch them to another connection or a token first.

When you create a runner with a connection, the dashboard lists only the sizes and regions your team may create; sizes your team's tier does not allow are hidden.

## Create an API token

Instead of connecting a team, you can paste a personal access token with **custom scopes**, so Manage Runners can do only what runners need. Select **Use a personal access token instead** under **DigitalOcean access** to show the token field.

1. Switch to the team for your runners. In the [DigitalOcean control panel](https://cloud.digitalocean.com/account/api/tokens), go to **API** > **Tokens** and select **Generate New Token**.
2. Enter a name and choose the **Expiration**. When a token expires, it no longer works and disappears from DigitalOcean, so Manage Runners can no longer pause, resume or delete the runners that use it, or create their burst runners. Choose no expiry, or [enter a new token](#changing-the-token) before the old one expires.
3. Choose **Custom Scopes** and select exactly these scopes:

   | Resource | Scopes |
   | --- | --- |
   | Account | `account:read` |
   | Droplet | `droplet:create`, `droplet:read`, `droplet:update`, `droplet:delete` |
   | Image | `image:read` |
   | Reserved IP | `reserved_ip:create`, `reserved_ip:read`, `reserved_ip:update`, `reserved_ip:delete` |
   | SSH key | `ssh_key:read` |
   | Tag | `tag:create` |

4. Select **Generate Token**, then copy the token. DigitalOcean shows it only once.
5. In the dashboard, select **Create Runner**, choose **DigitalOcean** under **Cloud provider**, select **Use a personal access token instead**, and paste the token into **DigitalOcean API Token**. Below the field, **How to create the token** repeats these steps and scopes and links to DigitalOcean's token page.

To let the dashboard hide the sizes your team may not create, also add `sizes:read` and `regions:read`; without them the token works, and all sizes are listed.

When you leave the token field, the dashboard checks the token: it reads the account, refuses it if DigitalOcean has locked the account, and lists the account's SSH keys. That check only needs `account:read` and `ssh_key:read`, so a token without the other scopes passes it. A missing scope fails only when an operation needs it, for example when the droplet is created, paused or deleted. If creating a new runner's droplet fails, the runner becomes **Unknown**; see [Troubleshooting](https://managerunners.com/docs/manual/troubleshooting/#a-digitalocean-token-or-limit-is-refused).

Manage Runners stores the token encrypted with the runner you entered it for, and uses it for that runner, its duplicates and its burst runners on DigitalOcean. Each runner has its own token, so different runners can use different DigitalOcean accounts. A runner that uses a connection keeps using it, and so do its duplicates and burst runners.

## What Manage Runners creates

In the token's account, Manage Runners creates:

- **one droplet per active runner** from DigitalOcean's Debian 13 image, named after the runner and its ID, for example `build-01-812999368881481087`, with the tag `managerunners-runner:<runner id>`, so Manage Runners can find it again;
- **a reserved IPv4 and a reserved IPv6 address** in the runner's region, for every runner except burst runners. They are reserved before the droplet is created and assigned to it once it is active. They stay in your account while the runner is paused and are deleted with the runner.

Such a droplet gets no IPv6 address of its own: the reserved IPv6 is its only public IPv6. [Burst runners](https://managerunners.com/docs/manual/autoscaling/) are never paused, so they get no reserved IPs: their droplets, which also carry the tag `managerunners-own-addresses`, keep their own public IPv4 and IPv6, which the dashboard shows once DigitalOcean has assigned them and which go with the droplet. Manage Runners does not create firewalls, volumes or SSH keys.

Droplets are created without DigitalOcean's droplet agent, which saves time on every boot. The control panel's **Droplet Console** is therefore not available for runner droplets; log in with SSH instead, see [SSH keys](#ssh-keys).

Do not delete or change runner droplets or their reserved IPs in the DigitalOcean control panel. Manage Runners does not watch the account for such changes. Pause, resume and delete runners from the dashboard or the CLI instead.

When you delete a runner, Manage Runners deletes the droplet first and then its reserved IPs. For some minutes after a droplet is gone, DigitalOcean may not release its reserved IPv4 yet. Manage Runners finishes the deletion of an active runner's addresses on its own; deleting a paused runner is refused in that case with a message that DigitalOcean has not released an IP yet, and you can delete it again a few minutes later.

## Products and locations

Products are DigitalOcean droplet sizes with a `do-` prefix, for example `do-s-2vcpu-4gb`. Manage Runners offers the Basic, General Purpose and CPU-Optimized sizes with at least 1 GB of memory that DigitalOcean offers for new droplets. All of them are x86; DigitalOcean has no ARM droplets.

The locations are the DigitalOcean regions Amsterdam (`ams3`), Frankfurt (`fra1`), London (`lon1`), New York (`nyc1`, `nyc3`), San Francisco (`sfo2`, `sfo3`), Atlanta (`atl1`), Toronto (`tor1`), Singapore (`sgp1`), Bangalore (`blr1`) and Sydney (`syd1`). Not every size is offered in every region; the dashboard shows where each one is available and at what price.

## SSH keys

Manage Runners does not create SSH keys. To log in to a runner's droplet:

1. Add your public key to the account in the DigitalOcean control panel under **Settings** > **Security**.
2. When you create or edit the runner, select the key under **DigitalOcean SSH Keys**. The list shows the keys of the account that the token belongs to.

Selected keys are added to the droplet's `root` account. As on Hetzner, SSH allows only `root` with a key, never a password, and fail2ban blocks repeated failed logins. Changing the selected keys of an active runner [recreates its droplet](https://managerunners.com/docs/manual/concepts/#changes-that-recreate-the-server).

## Labels and firewalls

Labels are not put on droplets: they are kept with the runner in Manage Runners, and GitHub runners still register them with GitHub. Unlike on Hetzner, a firewall cannot select your runners by one of your labels, so a label such as `role=ci-runner` has no effect on DigitalOcean.

Manage Runners creates no cloud firewall, so a runner's SSH port is reachable from the internet; only key login for `root` is possible. GitLab Runner and the GitHub Actions runner only make outgoing connections, so a runner needs no incoming rules for CI. If you add a DigitalOcean cloud firewall yourself, keep in mind that pausing and resuming a runner, and changes that recreate it, create a new droplet.

## Outbound traffic

A droplet's traffic leaves through its own, changing address unless it is routed through a reserved IP. On first boot, the droplet waits until both reserved IPs are assigned and then sends its outgoing IPv4 and IPv6 traffic through them, before GitLab Runner or the GitHub Actions runner registers. A timer restores these routes every minute. So jobs reach your GitLab instance and other services from the runner's reserved addresses, and allow lists that name them keep working across pause and resume.

Burst runners have no reserved IPs and send their traffic from their droplet's own addresses, which differ for every burst runner. A service that accepts only known addresses cannot list them in advance.

If the droplet's network configuration is reset while it runs, for example by restarting `systemd-networkd`, its traffic can leave through the droplet's own address for up to a minute, until the timer restores the routes.

## Billing

DigitalOcean bills droplets per second, with a minimum of 60 seconds, up to the size's monthly price. The prices in the dashboard are DigitalOcean's monthly net list prices in USD. A paused runner has no droplet, so it costs no droplet time, but its reserved IPv4 is no longer assigned and DigitalOcean charges USD 5 a month for an unassigned reserved IPv4. Reserved IPs that are assigned to a droplet, and reserved IPv6 addresses, are free. See [DigitalOcean's droplet pricing](https://docs.digitalocean.com/products/droplets/details/pricing/) and [reserved IP pricing](https://docs.digitalocean.com/products/networking/reserved-ips/details/pricing/).

Because DigitalOcean bills by the second, [autoscaling](https://managerunners.com/docs/manual/autoscaling/#billing-aware-scale-in) removes a DigitalOcean burst runner as soon as the load has been low long enough, without waiting for the end of a paid hour.

## Account limits

DigitalOcean limits how many droplets and reserved IPs an account may have. Every runner needs one droplet, one reserved IPv4 and one reserved IPv6; every burst runner needs only a droplet. New accounts get small limits: by default, DigitalOcean lets an account reserve only three IPs. Ask DigitalOcean to raise the limits before you create several runners or allow many [burst runners](https://managerunners.com/docs/manual/autoscaling/).

DigitalOcean also limits which droplet sizes a team may create, by the team's tier: lower tiers stop at smaller Basic and dedicated sizes. Only DigitalOcean support can raise a team's tier. Manage Runners lists every size it offers, but when you create a runner, change a runner's size or save a burst runner template, it checks with your token that DigitalOcean offers the chosen size in the chosen region to your team. If not, it refuses the change before anything is saved, because either the tier does not allow the size or the region has no capacity for it right now; see [Troubleshooting](https://managerunners.com/docs/manual/troubleshooting/#a-digitalocean-token-or-limit-is-refused).

When a limit is reached, DigitalOcean refuses the droplet or the reserved IP and Manage Runners shows its message with a hint, for example to delete unused reserved IPs or to ask DigitalOcean to raise the limit. Resuming a runner shows the error, and the runner stays paused. A new runner becomes **Unknown**, and Manage Runners deletes the reserved IPs it had just created for it. For burst runners, a reached limit is a [provider shortage](https://managerunners.com/docs/manual/autoscaling/#when-autoscaling-stops): autoscaling stays enabled, waits and tries again, and emails the organization's owners and editors once.

## Changing the token

To use a new DigitalOcean token, for example after revoking the old one, edit the runner and enter the new token. It must belong to the same account, since the runner's droplet and reserved IPs are there. Changing only the token does not recreate the droplet. If the runner was **Unknown** because the old token stopped working, saving the new token makes Manage Runners check the account again. See [Troubleshooting](https://managerunners.com/docs/manual/troubleshooting/#a-runner-is-unknown).

To switch a runner from a token to a connection, or back, edit it and choose the connection under **DigitalOcean access**, or select **Use a personal access token instead** and enter a token. Both must be for the team that holds the runner's droplet; another team is refused. A runner that uses a connection needs no change when the connection is renewed.
