Skip to main content
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

1

Open your project

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

Select the Worker resource type

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

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.
4

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.
5

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.
6

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

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.
CPU capacity in vCPU and memory in GB. Saving settings records the desired configuration. Select Redeploy to apply the saved compute settings to the running worker.
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.
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

Get a Worker

Update a Worker

Saving worker settings does not redeploy the running service. Select Redeploy after saving to apply the change. Runtime environment saves can roll the service; Build saves apply on the next build.

Redeploy

To manually trigger a new build and restart without pushing a commit:
Read the worker API reference for the optional redeploy.source selection (existing, branch or commit). Do not assume that an empty request fetches a new branch commit. Track the returned workflow until it succeeds or fails.

Branch Previews

Previews can inherit production environment values. This example uses variables: [] to avoid copying them. Supply the full preview-specific set when the application requires variables. Review databases, queues and external services before creation. See preview boundaries. Each branch in your repository can have its own isolated preview worker deployment. Create a preview via the API:
Each preview runs as a fully independent worker in your AWS account. For a full explanation, see Branch Previews.

Build and runtime variables

Use Build variables in the creation form to configure the first build. After creation, edit Environment → Build, select Save build variables, then Redeploy or rebuild the selected preview to apply changes. Build Save does not deploy or restart the running service. Values stay in your AWS CodeBuild project. For Docker builds, declare matching ARG NAME instructions in the stage that uses each variable. Values can become part of images or public bundles; use them for configuration, not secrets. Build variables are separate from Runtime variables. See Environment variables for scope defaults, previews, and examples. Use Runtime variables for the running worker process. Runtime saves can roll the service.
PUT replaces the complete editable set in the selected scope. Use runtime instead of build for runtime values.

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:

Metrics

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

Cost Estimate

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

Teardown

To delete a worker and remove the container service from your AWS account:
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.