Job DSL, Seed Jobs, Folder Hierarchies, Programmatic Job Creation, and Jenkins API Automation: Concepts, Architecture, and Mental Model

1. The practical problem: hundreds of UI-created jobs do not scale

Creating one Jenkins job in the UI is easy. Creating the same class of job for dozens of services, keeping every option consistent, proving who changed it and rolling back a bad bulk edit is not. Job DSL solves this by treating item definitions as reviewed Groovy-based desired-state code.

The dangerous part is equally important: Job DSL is not a harmless template engine. A seed job can create, update, disable or delete persisted Jenkins items. The generator therefore belongs in the controller trust model alongside JCasC, plugins and trusted Shared Libraries.

2. Mental model: source → seed → generated state

Read this flow from left to right. The Git commit is the desired-state input. The seed job supplies execution identity, workspace and build audit. Job DSL interprets the files under sandbox/approval rules. Jenkins then persists item configuration. Later builds of generated jobs are separate runs with their own source, queue, agent and artifacts.

flowchart TD
  A[Versioned Job DSL source\ncommit + files] --> B[Seed job\nfull name + build + identity]
  B --> C[Job DSL execution\nsandbox or approved script]
  C --> D[Desired folders and jobs\nfull names + ownership]
  D --> E[Created / updated / disabled / deleted items]
  E --> F[Generated-job builds\nqueue + agent + workspace]
  F --> G[Reports / artifacts / statuses]
  B --> H[Seed audit evidence\nconsole + generated objects + API]
  E --> H

The arrows matter. A green generated application build does not prove the seed source was safe. A green seed build does not prove every generated job later runs correctly. Persisted item configuration and build runtime are different states.

3. Terminology before commands

4. State boundaries you must keep separate

5. Read-only inspection before mutation

On the disposable controller, inspect rather than configure first. Record the values in a small evidence file:

# Controller/runtime evidence
curl -fsSI "$JENKINS_URL/login" | grep -i '^X-Jenkins:' || true
java -version

# Plugin versions through the authenticated API (token stored outside shell history)
curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  "$JENKINS_URL/pluginManager/api/json?depth=1" > evidence/plugins.json

# Existing items only; no POST and no mutation
curl -fsS --user "$JENKINS_USER:$JENKINS_API_TOKEN" \
  "$JENKINS_URL/api/json?tree=jobs[fullName,_class,color]" > evidence/items-before.json

Use an API token through a protected environment/file binding; never put a real token in lesson files or command history. API-token-authenticated POSTs are exempt from crumb requirements, while username/password scripted clients generally need the crumb/session flow.

6. Seed identity is part of the desired-state contract

A seed should not run with more authority than needed. In a strong design, the seed’s build identity can configure/create items in its platform/team folder and cannot administer the controller or mutate unrelated folders. When sandboxed Job DSL performs Jenkins access checks, a deliberate build identity is especially important; Authorize Project is one current mechanism for that.

Folder-relative generation helps but does not replace authorization. lookupStrategy: 'SEED_JOB' makes relative names resolve beneath the seed’s folder. Pair that with folder permissions and a test that an out-of-scope write is denied.

7. Job DSL is not Pipeline DSL

// Job DSL: creates a Pipeline job
pipelineJob('apps/api-ci') {
  description('[managed-by=job-dsl][owner=platform-lab]')
  definition {
    cpsScm {
      scm {
        git { remote { url('file:///workspace/app-repo.git') } }
      }
      scriptPath('Jenkinsfile')
    }
  }
}

// Pipeline DSL: executed later *by* the generated job
pipeline {
  agent { label 'linux-ci' }
  stages {
    stage('Test') { steps { sh './test.sh' } }
  }
}

The first script mutates Jenkins item configuration. The second governs one build’s runtime. Mixing them produces confusing syntax and trust failures.

8. Removed items: lifecycle, not garbage collection

When multiple Job DSL steps run in one seed build, apply DISABLE/DELETE removed-item actions only on the last relevant Job DSL step; otherwise an item can be disabled/deleted before a later step recreates it.

9. DevOps connection: generator evidence makes automation reproducible

A useful generated job has a chain you can reconstruct: DSL repository commit → seed full name/build/cause → sandbox/identity → generated item full name/config → later build source/queue/agent → reports/artifacts. If any link is implicit, debugging and governance become guesswork.

10. Common wrong approaches

• Give every developer permission to edit an admin-equivalent seed.
• Run arbitrary unsandboxed Groovy because “the source is in Git.”
• Use names with timestamps/random suffixes and call repeated generation idempotent.
• Delete jobs that merely happen to share a naming prefix.
• Use Job DSL to replace JCasC global configuration or Pipeline runtime logic.
• Treat a 200 API response as proof a queued/generated job completed successfully.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Job DSL plugin — current release, minimum core requirement, maintenance/security status and links to the API Viewer.
• Jenkins Pipeline Steps — Job DSL — current jobDsl parameters including sandbox, lookup strategy and removed-item actions.
• Job DSL upstream repository — getting started, Job DSL versus Pipeline DSL, and API Viewer guidance.
• Job DSL — Script Security — sandbox/approval behavior and build-identity implications.
• Script Security plugin — Groovy sandbox and signature-approval boundary.
• Folders plugin — folder hierarchy baseline used by the examples.
• Matrix Authorization Strategy — optional fine-grained folder/item permission model for the lab.
• Authorize Project plugin — optional explicit build identity used when exercising sandboxed Job DSL with access-control checks.
• Jenkins Remote Access API and CSRF protection — current API authentication/POST semantics.
• Jenkins LTS changelog and Java support policy.