Organization Folders, GitHub/GitLab/Bitbucket Discovery, Repository Onboarding, and Platform Automation: Concepts, Architecture, and Mental Model

1. The scaling problem

Chapter 22 automated branches inside one repository. Platform teams often manage tens or hundreds of repositories. Creating one Multibranch Pipeline by hand for every repository is repetitive, easy to drift and difficult to retire consistently. An Organization Folder solves that by asking a provider such as GitHub, GitLab or Bitbucket which repositories exist, applying discovery rules, and maintaining one Multibranch child per eligible repository.

The important boundary is that discovered does not mean trusted. A provider credential may be able to enumerate private repositories or register webhooks, while a repository Jenkinsfile may be contributor-controlled. Organization-scale automation must therefore keep discovery, build execution, credentials and protected deployment separate.

2. Mental model

Each arrow below owns different state and evidence. Read it before configuring anything.

flowchart TD
A[Provider organization/group + scoped identity] --> B[Provider API repository inventory]
B --> C[Discovery traits and filters]
C --> D[Organization Folder computation]
D --> E[Generated Multibranch child]
E --> F[Branch / PR indexing]
F --> G[Queued build on eligible agent]
G --> H[Reports / artifacts / status]
D --> I[Orphaned child + retention policy]
B --> J[Rate-limit / webhook / audit evidence]

The provider owns repository membership and API responses. Jenkins owns Organization Folder configuration, computation logs and generated child items. Each child owns branch indexing/build history. Agents own workspaces/processes. External deployment remains a separate system and must not be authorized merely because a repository was discovered.

3. State inventory before change

4. Read-only inspection first

Before changing filters or credentials, preserve the Organization Folder computation/scan log, list generated children, record current discovery traits and orphan policy, and capture provider quota information where available. Branch API documents organization event routing through controller logs and per-folder computation event logs; these are evidence, not files to edit by hand.

5. Provider plugins are similar—but not interchangeable

GitHub Branch Source, GitLab Branch Source and Bitbucket Branch Source all integrate repository discovery with Multibranch children, but authentication models, webhook APIs, fork trust, rate limits and visibility rules differ. A platform standard should name the exact provider plugin/version and provider permission model instead of using a generic “SCM token” assumption.

6. API budgets are production capacity

Organization scans multiply calls by repository count and traits. GitHub, GitLab and Bitbucket all rate-limit API traffic. A scan storm can make onboarding stale even when Jenkins itself is healthy. Record provider response headers/status, scan cadence and repository cardinality; prefer event-driven updates plus bounded reconciliation instead of constant full scans.

7. Ownership is part of onboarding

A child item without an accountable owner becomes a platform orphan long before the SCM repository disappears. Store or derive ownership from provider teams/topics/catalog metadata, and include it in onboarding evidence. Ownership should drive notification/escalation and decommission review—not grant Jenkins privileges automatically.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog — chapter baseline Jenkins 2.568.3 LTS, released 2026-09-02 and tested with Java 21 and 25; labs use Java 21.
• Branch API — version 2.1280.v0d4e5b_b_460ef; defines organizational folders, Multibranch children and event/computation logging.
• Folders — version 6.1106.v3a_d9a_6d2465e.
• Credentials — version 1511.v2e3cb_0008ef0.
• GitHub Branch Source — version 1983.vfa_27ed961853, requiring Jenkins 2.541.1.
• GitLab Branch Source — version 743.ve0c8154a_8da_b_, requiring Jenkins 2.504.3.
• Bitbucket Branch Source — version 937.3.10, requiring Jenkins 2.541.3.
• GitHub REST API rate limits — authenticated users normally receive 5,000 requests/hour; GitHub App installation limits vary and include higher Enterprise Cloud allowances.
• GitLab.com rate limits — authenticated limits are plan-dependent; self-managed limits can differ.
• Bitbucket Cloud API request limits — authenticated and anonymous requests have separate rolling limits.

Version note — 2026-09-17: mandatory exercises are a local faithful simulation and require no external SCM account. The optional real-provider path must re-check the exact provider plugin version, security advisories, API permissions, webhook behavior, rate-limit headers and provider-plan limits before use. Never substitute a broad personal/admin token merely to make discovery easier.