Job DSL, Seed Jobs, Folder Hierarchies, Programmatic Job Creation, and Jenkins API Automation: Configuration, Design Choices, and Tradeoffs

1. Job DSL versus JCasC versus REST/XML

Use each mechanism for the state it models naturally. “Everything as Groovy” is not a governance strategy.

2. Platform seed versus team/folder seeds

A central platform seed gives one governance point and consistent defaults. It also concentrates permissions and blast radius. Team seeds reduce scope and ownership ambiguity, but require versioned conventions so every team does not invent incompatible DSL patterns.

3. Sandboxed versus approved DSL

Sandboxing is the default design target for team-authored DSL. Job DSL integrates with Script Security: safe DSL methods are available while unsafe Groovy operations are rejected or require signature approval. Jenkins access-control checks then matter, so the seed should run as a real constrained identity.

Administrator-approved unsandboxed DSL can be justified for tightly controlled platform code that truly needs unsupported operations, but approval grants in-process Groovy power. Treat that repository like a controller plugin: protected reviewers, versioned releases, tests and rollback.

4. IGNORE, DISABLE and DELETE are governance states

The Job DSL removedJobAction setting turns a missing previously-generated job into an explicit lifecycle decision. Generated-item lifecycle should mirror confidence:

1. IGNORE while adopting Job DSL or when ownership cannot be proven.
2. DISABLE when a generated job is intentionally retired but history/evidence should remain.
3. DELETE only after retention, export/backup and ownership checks confirm removal is intended and recoverable.

The safest production pattern often separates “remove from active service” and “purge after retention” into different changes.

5. Folder-scoped generation

Use a predictable folder hierarchy such as teams/payments/**. Place the team seed inside its folder, use lookupStrategy: 'SEED_JOB' and authorize that identity only for the folder subtree. Test the boundary by attempting an out-of-scope generation in a disposable clone and recording the denial.

Names are not ACLs. A script that says team-a/foo is not secure if the seed identity can also create ../admin-equivalent root items through other APIs.

6. Remote API design choices

Use API tokens for scripted clients and guard exact item paths. For POSTs authenticated with username/password, Jenkins CSRF protection generally requires a crumb/session; API-token requests are exempt. Avoid brittle “latest job” or ambiguous delete operations. Read the job full name and build number you intend to act on.

Direct config.xml mutation should be exceptional because it bypasses the higher-level desired-state contract. If used, capture the previous XML/config digest and reconcile the change back into Job DSL or documented UI ownership.

7. Generated-item ownership contract

A robust generated item carries multiple independent clues:

• Job DSL plugin tracking that links it to the seed.
• Human-readable description such as [managed-by=job-dsl][seed=teams/payments/seed].
• SCM commit stored as seed artifact/build metadata.
• Folder placement and ACL inheritance.
• Retention/lifecycle policy and recovery owner.

No single clue is sufficient for destructive deletion; together they make ownership auditable.

8. Worked scenario: three teams on one controller

Platform owns global security/JCasC and creates teams/a, teams/b and teams/c. Each team owns a Job DSL repository and seed inside its folder. Shared job templates live in a versioned library/module, not a mutable controller script.

9. Version and migration policy

Version the DSL schema just like a Shared Library API. When changing job names, parameters, branch sources or credentials IDs, describe the migration and compatibility impact. Avoid silently replacing a job under a new name because that fragments history and downstream references.

Before a wide generator rollout: run in a clone, compare generated XML/config, run representative jobs, inspect removed-item candidates, then promote the same reviewed DSL commit.

10. Decision checklist

• Which state layer am I managing: controller, item, build runtime or external system?
• Which identity executes the generator, and what can it mutate?
• Can the same outcome be expressed inside the supported DSL/API Viewer?
• How is generated-item ownership proven?
• What happens to removed jobs, views and history?
• How do I roll back both DSL source and persisted controller state?

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.