All jobs

Add Background Jobs to a Vapor App from a Linear Issue

Yes. Label the Linear issue and an agent adds Vapor Queues, moves the work the issue names into a job with a worker and tests, and opens a PR that links it.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the issue, then the app. In an app shaped like vapor/template-fluent-postgres, Package.swift uses swift-tools-version 6.3 and depends on vapor from 4.121.4, fluent from 4.13.0, fluent-postgres-driver from 2.12.0 and swift-nio from 2.101.0, with upcoming-feature flags such as ExistentialAny and MemberImportVisibility turned on for both targets. configure.swift connects to Postgres from DATABASE_HOST, DATABASE_PORT, DATABASE_USERNAME, DATABASE_PASSWORD and DATABASE_NAME, adds the CreateTodo migration and registers routes. routes.swift serves / and /hello and mounts TodoController, which lists, creates and deletes Todo models through TodoDTO. entrypoint.swift bootstraps logging and calls app.execute(), which is what will run a worker command later. There is no queue, no scheduler and no worker; whatever the issue wants off the request path currently has nowhere to go.

The issue decides the driver. Vapor's Queues package needs a backing store, and the two common drivers are Redis through queues-redis-driver and the database through queues-fluent-driver. The app already runs Postgres, so if the issue does not name Redis the agent proposes the Fluent driver and says why: one fewer service in docker-compose.yml, and the jobs table rides the existing migrations. It adds the packages to Package.swift and the products to the executable target, and in configure.swift adds the driver's migration and app.queues.use(...) with the connection the app already has. The InternalImportsByDefault and MemberImportVisibility settings mean every new file needs explicit imports, which the compiler enforces, so the agent builds early and often.

Then it writes the job. For an issue such as send a confirmation email when a todo is created, off the request path, that is Jobs/TodoCreatedJob.swift, a struct conforming to AsyncJob with a Codable payload carrying the todo id and title, and a dequeue that does the work and logs with the request-independent context.logger. TodoController.create dispatches it with req.queue.dispatch(TodoCreatedJob.self, payload) after save, so the response no longer waits on the side effect. configure.swift registers the job with app.queues.add(TodoCreatedJob()). A worker is started with swift run TemplateFluentPostgres queues, so docker-compose.yml gets a queues service built from the same image with that command, beside the existing migrate and revert services whose replicas: 0 pattern the agent copies for the one-shot commands. For development, app.queues.startInProcessJobs() under a .development check keeps a single process useful.

Tests follow the existing suite. Tests/TemplateFluentPostgresTests uses Swift Testing with @Suite("App Tests with DB", .serialized) and a withApp helper that calls configure, autoMigrate and autoRevert around each test against a real Postgres. The agent adds a test that switches the queue to the Queues package's test driver, posts to /todos, and asserts that one TodoCreatedJob was dispatched with the new todo's title, then runs the job inline and asserts its effect. In the sandbox it starts the db service from docker-compose.yml or a local PostgreSQL with the same DATABASE_* values, runs swift build and swift test, and runs the worker command once to show it connects and waits for jobs.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "A Linear issue labelled agent asks for background jobs in this Vapor app. Read Package.swift, Sources/TemplateFluentPostgres/configure.swift, routes.swift, entrypoint.swift, Controllers/TodoController.swift, Models/Todo.swift, DTOs/TodoDTO.swift, Migrations/CreateTodo.swift, Tests/TemplateFluentPostgresTests/TemplateFluentPostgresTests.swift, docker-compose.yml and Dockerfile first. Add Vapor Queues with the driver the issue names; if it names none, use the Fluent driver on the existing Postgres and say why. Register the driver and its migration in configure.swift, write the job the issue describes under Sources/TemplateFluentPostgres/Jobs as an AsyncJob with a Codable payload, dispatch it from the controller after the save, and add a queues service to docker-compose.yml that runs the worker command from the same image. Enable in-process jobs only in the development environment. Add a Swift Testing test that uses the Queues test driver to assert the job is dispatched from the route with the right payload and runs correctly. Start Postgres in the sandbox, run swift build and swift test, run the worker command once, and open a pull request that links the issue and quotes the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that changes Package.swift and Package.resolved, configure.swift and TodoController.swift, adds Sources/TemplateFluentPostgres/Jobs/TodoCreatedJob.swift, adds a queues service to docker-compose.yml, and extends the test file with a dispatch test. The description links the Linear issue, names the driver chosen and the alternative, and lists the new environment or compose pieces, which for the Fluent driver is only the new migration.

The evidence is the sandbox run: swift build completing on the 6.3 toolchain the Dockerfile names, swift test output listing the existing todo tests and the new dispatch test, and the worker's startup log from swift run TemplateFluentPostgres queues. No email or external call is claimed to have been sent; the job's effect in the test is whatever the issue asked for, asserted in the test.

Before merging, a reviewer checks that the dispatch sits after the save so a failed insert enqueues nothing, that the payload carries ids rather than whole models, and that the production deployment runs at least one worker process, which the compose file now shows but a cloud deployment must mirror. A request to add a retry count or a scheduled cleanup job is a follow-up on the same session.

Run it on every Linear issue labelled agent

Sign in to Linear once with POST /me/connections {"type": "app", "name": "linear"} and finish the authorize URL in the console. Then add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled, naming the label in config.labels. The trigger adds the issue after the prompt, so the job's name, payload and the driver choice come from the issue text; the automation's max_runs_per_hour caps how many issues it takes on. Changes made by an app integration never fire it.

Each labelled issue runs in its own sandbox with its own Postgres and opens its own pull request. Once the Queues package is in, later issues such as nightly cleanup of done todos reuse it: the agent reads the existing Jobs directory and adds a scheduled job with app.queues.schedule instead of a second queue system.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

Adding a queue to a Swift server is a compile-and-run problem more than a design problem: the package resolution, the explicit imports the upcoming-feature flags demand, the migration order, and a worker that actually connects. Each of those fails loudly only when built and run against Postgres, and the agent does that in its own sandbox with the 6.3 toolchain before the pull request exists, instead of leaving a reviewer to discover a missing import Queues on their own machine.

The record stays with the pull request: the issue text, the files read, the swift build and swift test output and the worker log are all in the run's transcript. Nothing is deployed and no external service is called; the pull request links the issue and a person merges when the driver choice and the payload shape are what they want.

Frequently asked questions

Redis or the database for the queue?

Whichever the issue names. When it names neither, the agent proposes the Fluent driver on the Postgres the app already runs, because it adds no service to docker-compose.yml, and states the trade-off: Redis is the more common choice at higher job volumes and is a one-line driver swap later.

How does the worker run in production?

As a second process from the same image, started with the queues command. The pull request adds a queues service to docker-compose.yml next to app, migrate and revert, and the description says a cloud deployment needs the same second process or no job will ever run.

Will it make the existing tests slower or flaky?

The new test uses the Queues test driver, which records dispatches in memory and runs jobs when the test asks, so nothing waits on a worker. The suite keeps its serialized, migrate-and-revert pattern from the existing withApp helper.

Can jobs run inside the web process during development?

Yes. The agent enables startInProcessJobs only when the environment is development, so swift run alone processes jobs on a laptop while production keeps the separate worker.

What goes in the job payload?

Identifiers and small values, not models. The TodoCreatedJob payload carries the todo id and title as a Codable struct, and the job reloads anything else it needs from the database when it runs, so a stale copy of the model is never acted on.

More Vapor jobs

The same job on other stacks

Keep reading