Deploy a Background Worker from GitHub to AWS

A worker in Springwinter is a long-running background process built from your GitHub repository and run as a container inside your own AWS account. Unlike web servers, workers expose no HTTP port and receive no public URL — they run continuously in the background, processing work as fast as your code allows.

Use Cases

Workers are the right resource type for any process that runs independently of incoming HTTP traffic:

Queue Consumers

Pull jobs from SQS, Redis, or any other queue and process them in a tight loop.

Scheduled Jobs

Run periodic tasks such as report generation, cache warming, or data aggregation on a fixed schedule.

Data Pipelines

Ingest, transform, and load data between systems without tying up a web server.

Webhook Processors

Consume events from third-party services and take action asynchronously.

Requirements

Before you deploy a worker, make sure you have:

A GitHub repository with a Dockerfile or a build setup that produces a runnable image.
An AWS account connected to Springwinter. See Connect Your AWS Account.
A GitHub account connected via the Springwinter GitHub App. See Connect GitHub.

Deploy a Worker

Open your project

Navigate to your project in the Springwinter dashboard and click Add resource.

Select the Worker resource type

Choose Worker from the resource type list. You will be taken to the worker configuration form.

Select a repository and branch

Pick the GitHub repository and the branch to track. Springwinter builds a new image and redeploys the worker on every push to that branch when auto-deploy is enabled.

Set the start command

If your Dockerfile does not define a default command, or you want to override it, enter the start command — for example, python worker.py or node dist/worker.js.

Choose a compute size

Select the CPU units and memory allocation for the container. Larger workers can process more jobs in parallel or handle heavier in-memory workloads.

Deploy

Click Deploy. Springwinter builds the image and starts the container. The worker begins running immediately once the container reaches a running state.

Configuration Options

Source

The GitHub repository and branch your worker is built from. Enable auto-deploy to automatically rebuild and restart the worker whenever you push a new commit to the tracked branch.

Compute size

CPU units and memory (MiB) assigned to the container. You can update the compute size at any time — Springwinter stops the current container and starts a replacement with the new allocation.

Auto-deploy

When enabled, every push to the tracked branch triggers a new build and a rolling restart of the worker. Disable auto-deploy if you want to control exactly when the worker is updated.

Environment variables

Injected into the container at launch. Use environment variables to pass connection strings, API keys, and feature flags to your worker process. See Environment Variables.

API Reference

Create a Worker

POST /api/projects/{project_id}/workers
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "my-background-worker",
  "repository": "my-org/my-app",
  "branch": "main",
  "start_command": "python worker.py",
  "cpu": 256,
  "memory": 512,
  "auto_deploy": true
}

Get a Worker

GET /api/projects/{project_id}/workers/{id}
Authorization: Bearer <token>

Update a Worker

PATCH /api/projects/{project_id}/workers/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "cpu": 512,
  "memory": 1024
}

Redeploy

To manually trigger a new build and restart without pushing a commit:

POST /api/projects/{project_id}/workers/{id}/redeploy
Authorization: Bearer <token>

Springwinter fetches the latest commit on the tracked branch, builds a fresh image, and replaces the running container.

Branch Previews

Each branch in your repository can have its own isolated preview worker deployment. Create a preview via the API:

POST /api/projects/{project_id}/workers/{id}/previews
Authorization: Bearer <token>
Content-Type: application/json

{
  "branch": "feature/new-processor"
}

Each preview runs as a fully independent worker in your AWS account. For a full explanation, see Branch Previews.

Environment Variables

Retrieve the current environment variables for a worker:

GET /api/projects/{project_id}/workers/{id}/environment
Authorization: Bearer <token>

Replace all environment variables at once:

PUT /api/projects/{project_id}/workers/{id}/environment
Authorization: Bearer <token>
Content-Type: application/json

{
  "DATABASE_URL": "postgresql://user:pass@host:5432/db",
  "REDIS_URL": "rediss://cache-endpoint:6379",
  "QUEUE_NAME": "jobs"
}

PUT replaces the entire set of environment variables. Any keys not included in the request body are removed. See Environment Variables for full details.

Logs

Worker output (stdout and stderr) is forwarded to CloudWatch and surfaced in the Springwinter dashboard under the Logs tab. You can also fetch logs via the API:

GET /api/projects/{project_id}/workers/{id}/logs
Authorization: Bearer <token>

Metrics

CPU utilization and memory usage for your worker are available from the Metrics tab or via the API:

GET /api/projects/{project_id}/workers/{id}/metrics
Authorization: Bearer <token>

Cost Estimate

Retrieve the current cost estimate and monthly run rate for a worker:

GET /api/projects/{project_id}/workers/{id}/cost
Authorization: Bearer <token>

Teardown

To delete a worker and remove the container service from your AWS account:

DELETE /api/projects/{project_id}/workers/{id}
Authorization: Bearer <token>

Deleting a worker stops the container immediately. Any in-flight jobs the worker is processing will be interrupted.

Workers share the same environment variable API as web servers. Pass your cache connection string or database URL as an environment variable so the worker can connect to other resources in the same project without any hard-coded configuration.

Get Started

Core Concepts

Deploy

Observability

Account & Team

Deploy a Background Worker from GitHub to AWS

Use Cases

Queue Consumers

Scheduled Jobs

Data Pipelines

Webhook Processors

Requirements

Deploy a Worker

Configuration Options

API Reference

Create a Worker

Get a Worker

Update a Worker

Redeploy

Branch Previews

Environment Variables

Logs

Metrics

Cost Estimate

Teardown

​Use Cases

Queue Consumers

Scheduled Jobs

Data Pipelines

Webhook Processors

​Requirements

​Deploy a Worker

​Configuration Options

​API Reference

​Create a Worker

​Get a Worker

​Update a Worker

​Redeploy

​Branch Previews

​Environment Variables

​Logs

​Metrics

​Cost Estimate

​Teardown

Use Cases

Requirements

Deploy a Worker

Configuration Options

API Reference

Create a Worker

Get a Worker

Update a Worker

Redeploy

Branch Previews

Environment Variables

Logs

Metrics

Cost Estimate

Teardown