How to Add Worker Components on DigitalOcean App Platform

intermediate 8 min read Updated 2026-03-24

Quick Answer

Add workers via Control Panel by selecting Worker type and configuring name/branch/instance size, or update app spec with workers array via CLI/API. Workers handle background tasks with outbound-only access. Common issues like repo errors fixed by verifying Git permissions and specs; deployment takes 10-30 minutes.

Get DigitalOcean App PlatformPartner

Try DigitalOcean App Platform Full DigitalOcean App Platform Review

Prerequisites

DigitalOcean account with billing enabled
Existing App Platform app
Source code repository (GitHub/GitLab/Bitbucket) with access
Personal access token for CLI/API (optional)
doctl CLI installed for automation

Step-by-Step Instructions

Navigate to Apps in Control Panel

Go to the Apps page in the DigitalOcean Control Panel at cloud.digitalocean.com/apps. Select your existing app from the list, then click the Add components button.

Choose Source Code Deployment

From the dropdown, select Create resources from source code. On the Add resources screen, enter a unique Name for your worker component.

Select Worker Type and Configure

Set Resource type to Worker. Specify the Branch from your Git repo and enable automatic redeploys if needed. Choose Instance size with shared or dedicated CPUs (recommended for intensive apps).

Dedicated CPUs ensure consistent performance for resource-heavy workers.

Set Environment Variables

Add Environment variables for secrets or config. For app-level vars available to all components, click Edit in the App-level environment variables section, add key-value pairs, and select scope.

Encrypt sensitive values to obscure them in logs.

Review and Deploy Worker

Review configuration and pricing in the Summary section, then click Create. App Platform auto-builds and deploys the worker. View/update later via Settings tab.

Install and Authenticate doctl CLI

For CLI method, install doctl, create a personal access token, and authenticate with doctl auth init using the token.

Update App Spec for Worker

Edit your app spec file (e.g., your-app.yaml) adding a workers section:

workers:
  - name: api
    git:
      branch: main
      repo: your/repo
    instance_size_slug: basic-xxs

Use valid YAML with correct repo details.

Deploy via CLI Command

Run doctl apps update <app-id> --spec your-app.yaml, replacing <app-id> with your app ID.

Prepare API Token and Endpoint

For API, create a personal access token. Send PUT request to https://api.digitalocean.com/v2/apps/{id} with Authorization: Bearer $TOKEN and JSON body including workers array.

Test token permissions first.

Monitor Deployment and Logs

After deployment via any method, check app dashboard for build status, logs, and worker health. Workers initiate outbound requests only.

Use logs for debugging build failures.

Common Issues & Troubleshooting

"Invalid repository" or "Repository not found" error

Verify Git OAuth integration or personal access token has repo read permissions. Test by cloning repo manually and check DigitalOcean settings.

Build or deployment failures

Review build logs in app dashboard, validate YAML/JSON spec syntax, ensure compatible instance size, and check environment variables.

Worker cannot receive incoming requests

Workers are non-routable for background tasks only; they initiate outbound HTTP. Use internal component networking via http://component-name.

Spec update not applying via CLI/API

Confirm app ID is correct, token has write access, and spec file path is accurate. Use --format flag to verify output.

Scaling or performance issues

Switch to dedicated CPUs for intensive workloads and adjust autoscaling in instance settings.

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official DigitalOcean App Platform website before purchasing.

Visit DigitalOcean App Platform View DigitalOcean App Platform Pricing