Skip to main content

Connect DigitalOcean

Tasks call DigitalOcean through qbash.integrations.digitalocean with a personal access token you store on the Connectors page. The token covers the account, billing, Droplets, App Platform, managed databases, Kubernetes, DNS and uptime checks. Spaces object storage uses a separate access key pair, which you add to the same credential only if a task reads or writes Spaces.

After you connect DigitalOcean, you can add its tools to a qbash MCP server for ChatGPT, Claude and other MCP clients, or call it from a Python task. The DigitalOcean MCP server page lists what the connector can do.

The writes are limited to Droplet power actions, starting an app deployment, DNS record changes and Spaces object uploads and deletes. No method creates or destroys a Droplet, app, database or cluster.

Create a personal access token​

  1. Sign in to the DigitalOcean control panel and select the team the task should read.
  2. Open API in the left menu. On the Tokens tab, click Generate New Token.
  3. Name the token and choose when it expires. When the token expires, calls fail until you paste a new one into the credential.
  4. Choose the scopes. Full Access grants every read and write on the team. Read Only grants every read and no writes. Custom Scopes lets you pick each resource, which is the safer choice for a task.
  5. For a reporting task, select the read scope of each resource it uses, such as account:read, droplet:read, monitoring:read, app:read, database:read, kubernetes:read, domain:read, uptime:read and billing:read. Keep account:read, because qbash checks a new token by reading the account.
  6. Add write scopes only for the methods a task calls: droplet:update for droplet_action, app:update for create_app_deployment, and domain:create, domain:update or domain:delete for the DNS record methods.
  7. Click Generate Token and copy it. DigitalOcean shows the token once, and it starts with dop_v1_.

Create Spaces keys (optional)​

The Spaces methods (list_spaces_buckets, list_spaces_objects, get_spaces_object, put_spaces_object and delete_spaces_object) sign their requests with a Spaces key pair. Skip this section if no task uses them.

  1. In the control panel, open Spaces Object Storage, then the Access Keys tab, and click Create Access Key.
  2. Choose Full Access to reach every bucket, or Limited Access to grant access to named buckets. Limited access is either read only or read, write and delete. A task that only reads needs read access on its buckets. A limited key cannot list buckets, so list_spaces_buckets returns an access error for it, while the other Spaces methods work on the buckets it was granted.
  3. Name the key and create it. Copy the access key and the secret key. The secret key is shown once.
  4. Note the region slug of the buckets, such as nyc3 or fra1. It appears in each bucket's URL, as in my-bucket.nyc3.digitaloceanspaces.com. One credential reads one region, so buckets in another region need a second credential.

Add the credential in qbash​

  1. Open Connectors, then DigitalOcean, and click Connect.
  2. Give the credential a name and paste the personal access token. qbash checks the token with DigitalOcean before saving it.
  3. To use Spaces, paste the Spaces access key and secret key and enter the region slug, such as nyc3. Fill in all three Spaces fields or leave all three blank. qbash checks new Spaces keys with DigitalOcean before saving them.
  4. In the task editor, open Resources → Integrations, and select the credential. See Connect resources.

To edit the credential later, leave a secret blank to keep the saved one.

Call DigitalOcean from a task​

This task checks an App Platform app's latest deployment and logs the end of its build output when the deployment failed. list_apps returns app ids.

app_id = "4f6c71e2-1e90-4762-9fee-6cc4a0a9f2cf"

result = qbash.integrations.digitalocean.list_app_deployments(app_id=app_id, per_page=1)

if not result["deployments"]:
    qbash.log("The app has no deployments yet.")
else:
    latest = result["deployments"][0]
    qbash.log(f'{latest["id"]} {latest["phase"]} {latest.get("cause")}')

    if latest["phase"] == "ERROR":
        build = qbash.integrations.digitalocean.get_deployment_logs(
            app_id=app_id,
            deployment_id=latest["id"],
            log_type="BUILD",
        )
        qbash.log(build["logs"][-4000:])

Deployments come back newest first. The SDK Reference lists every method with its parameters and return values.

Add test data​

A new team has nothing to list, so most list methods return empty pages until you create these:

  • A Droplet. Create the smallest Basic Droplet in any region and turn on Monitoring under advanced options, which installs the metrics agent that get_droplet_metrics reads. Droplets bill by the hour, so destroy it when you finish testing.
  • An App Platform app. Create an app from a static site repository, such as DigitalOcean's sample HTML app. Static sites fall within App Platform's free allowance. To see a failed build, push a commit that breaks the build and read the ERROR deployment's logs.
  • A domain. Open Networking, then Domains, and add a domain you own. DigitalOcean stores its records even before the registrar points at DigitalOcean's name servers, so create_domain_record and list_domain_records work on a test domain.
  • An uptime check. Open Monitoring, then Uptime, and create a check against the app's URL for list_uptime_checks and get_uptime_check_state.
  • A Spaces bucket. Create a bucket in the region on the credential and upload a small file, or write one with put_spaces_object.

Details that affect results​

  • List methods take page and per_page, with up to 200 items per page, and return next_page. Pass next_page back as page until it is None. list_databases and list_spaces_buckets return everything in one call. list_spaces_objects pages differently: pass next_marker back as marker while is_truncated is True.
  • cpu values from get_droplet_metrics are cumulative CPU seconds per mode. Compute usage from the change between two points. filesystem_free and filesystem_size are bytes, with one series per mounted filesystem. The window defaults to the last hour. An empty series list usually means the Droplet does not run the metrics agent.
  • get_deployment_logs reads the app's active deployment when you leave out deployment_id, and the latest deployment when none is active. A failed deployment is never the active one, so pass its id from list_app_deployments to read why it failed.
  • Only the last 1 MB of logs comes back, and truncated is True when earlier lines were cut. RUN logs of a running app can come back empty, because DigitalOcean serves those as a live stream that this method does not read.
  • droplet_action returns as soon as DigitalOcean accepts the action. action.status starts as in-progress, so read the Droplet with get_droplet to see when its status changes.
  • DigitalOcean allows each token 5,000 requests per hour and 250 per minute. A task that walks every page of a large list on a frequent schedule can reach the limit.
  • list_spaces_buckets returns only the buckets in the credential's region.
  • get_spaces_object and put_spaces_object handle objects up to qbash's 5 GB file limit. get_spaces_object returns a qbash file reference, which other methods accept as a file. Text passed as content is limited to 500 MB.
  • Balance and invoice amounts are decimal strings in US dollars, such as "23.44".
  • get_database and list_databases remove credentials before the result reaches the task: passwords, connection URIs, and Kafka access keys and certificates.
Last updated on