Sitelet https://github.com/compose-spec/compose-spec/pull/642
Skip to content

introduce Jobs - #642

Open
ndeloof wants to merge 3 commits into
compose-spec:mainfrom
ndeloof:jobs
Open

ndeloof wants to merge 3 commits into
compose-spec:mainfrom
ndeloof:jobs

Conversation

@ndeloof

@ndeloof ndeloof commented Apr 17, 2026 •

Copy link
Copy Markdown
Collaborator

What this PR does / why we need it:

Introduce jobs top-level element and a layered container specification

Motivation

Services are long-running processes, but Compose users also need to define one-shot tasks — database migrations, batch processing, scheduled cleanups. A common hack is to declare those as "services" with a profile so they are excluded by default, and invoke them with docker compose run.
This PR introduces jobs as a first-class top-level element in the Compose specification to address this gap.

To avoid duplicating the full container configuration schema between element types, the shared configuration is extracted as a layered specification:

  • container_spec — the attributes of a single container, shared by anything that runs one: services, jobs, and run-to-completion init containers (pre_start hooks);
  • workload_spec — orchestrated-workload attributes (build, depends_on, expose, healthcheck, ports, stdin_open, tty), shared by services and jobs;
  • service-only attributes (attach, container_name, restart, scale, deploy, develop, lifecycle hooks, …) stay in the services document.

As a direct consequence, pre_start hooks become a full container specification (allOf [container_spec] + per_replica) instead of a hand-curated 7-attribute subset: undeclared attributes are inherited from the service, declared ones override with the merge-file rules — the direction proposed in #656. Attributes excluded from inheritance by that proposal (ports, healthcheck, depends_on, build, …) are excluded by construction: they live in workload_spec, which hooks do not compose.

jobs:
    db-migration:
      image: myapp:latest
      command: python manage.py migrate
      triggers:
        manual: true

    cleanup:
      image: busybox
      command: sh -c 'find /data -mtime +30 -delete'
      triggers:
        schedule: "0 3 * * *"

Note: this requires JSON Schema draft 2020-12 as proposed on compose-spec/compose-go#864 so we can use unevaluatedProperties for composition by allOf/$ref

Which issue(s) this PR fixes:
Fixes #92
Addresses #656 (schema side)

@ndeloof
ndeloof requested a review from glours April 17, 2026 06:24
@ndeloof

ndeloof commented Apr 17, 2026

Copy link
Copy Markdown
Collaborator Author

cc @JulienBreux

@ndeloof
ndeloof marked this pull request as ready for review May 19, 2026 12:41
@JulienBreux

Copy link
Copy Markdown
Contributor

Very good, how can I help 🤗

@glours

glours commented Jun 22, 2026

Copy link
Copy Markdown
Contributor

@JulienBreux you’ll need to wait a little bit, this PR is only a draft for now. We still have some internal design work to finish first, as this needs to be supported on the Engine and CLI sides as well 😉

But we’re working on it 🎉

@JulienBreux

Copy link
Copy Markdown
Contributor

@JulienBreux you’ll need to wait a little bit, this PR is only a draft for now. We still have some internal design work to finish first, as this needs to be supported on the Engine and CLI sides as well 😉

But we’re working on it 🎉

Thanks! Brilliant! That's a really good news.

ndeloof and others added 3 commits September 17, 2026 11:07
Add the jobs top-level element for run-to-completion containers, and
extract the container configuration shared across element types as a
layered specification:

- container_spec: attributes of a single container, shared by anything
  that runs one — services, jobs, and pre_start init containers
- workload_spec: orchestrated-workload attributes (build, depends_on,
  expose, healthcheck, ports, stdin_open, tty), shared by services and
  jobs
- service-only attributes (attach, container_name, restart, scale,
  deploy, develop, extends, links, external_links, provider, lifecycle
  hooks) stay in the services document

pre_start hooks become a full container specification (allOf
[container_spec] + per_replica) instead of a hand-curated 7-attribute
subset: undeclared attributes are inherited from the service, declared
ones override with the merge-file rules (compose-spec#656).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
manual defaults to true — any job can be executed by an explicit run
command; an explicit false forbids it, for scheduled jobs whose
out-of-schedule execution would be harmful. manual and schedule may now
be combined (anyOf instead of an exclusive oneOf).

Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>
The spec-build stage introduced by "introduce Jobs" cats jobs.md and
container_spec.md into spec.md but forgot workload_spec.md, so build,
depends_on, expose, healthcheck, ports, stdin_open and tty silently
dropped out of the generated single-file spec. Add the missing cat and
regenerate spec.md accordingly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Signed-off-by: Nicolas De Loof <nicolas.deloof@gmail.com>

@aevesdocker aevesdocker left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good for the release. There are a few 'AI-isms' but I can see to that in a follow-up after the release lands ( + then get it onto the docs site)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: Scheduled Jobs

4 participants