Stop Pretending the Physical World Is Not There
Developer onboarding crosses physical boundaries.
That sounds strange only because software teams often pretend setup is purely digital. It is not. A developer arrives in a building, on a network, with a device, with an identity, under company policy, behind firewalls, certificates, and access rules.
Setup-as-code fails when it hides those boundaries.
The goal is not to automate the impossible. The goal is to stop mixing physical reality with tool installation as if both were the same kind of step.
| Boundary | Example | Setup-as-code treatment |
|---|---|---|
| Room | the developer needs an actual place to work | named prerequisite |
| Badge | the developer needs entry to the building | owned human workflow |
| Wi-Fi | the workstation needs network path to company services | probe where possible |
| Identity | account, MFA, groups, SSH keys | probe and evidence |
| Git server | clone, fetch, branch, push permissions | executable readiness check |
| Workstation | OS, shell, editor, certificates, package manager | automated bootstrap |
| Privilege | standard-user rights, admin grants, elevation windows | probe what is permitted, own the elevation grant |
The physical boundary is not a defect in the model. It is part of the model.
A Boundary Can Be Tested or Owned
Each boundary should be classified as either testable, ownable, or both.
A testable boundary can be probed:
can resolve git.company.local
can establish TLS chain to package mirror
can authenticate to Git
can clone onboarding-readiness repository
can run docker info
can open VS Code with required extensions installed
can install a required tool per-user without adminAn ownable boundary cannot be fully automated, but it can be named:
badge issued by Facilities
manager approved repository group
security enrolled device certificate
desk assigned by Office team
MFA enrollment completed by Identity team
temporary local admin granted by the Endpoint teamThe difference matters. A setup script that says "Git clone failed" after a newcomer arrives is useless. A setup model that says "IdentityAccess.GitGroupMembership missing before arrival" gives the company something it can fix.
This is one reason to model onboarding with DDD. A boundary with a name can have an owner, a state, a probe, and an event.
Privilege is the boundary that is both at once, and the one corporate setups most often pretend away. Phase 1 decided it: on a managed machine the developer is usually a standard user, not a local admin. So the testable half asks what is permitted without elevation — can a tool install per-user (winget install --scope user), can the user profile and PATH be written, can certificates be added to the user store. The ownable half is the elevation itself: when admin is genuinely required, it must be temporary and owned — a granted grace period, a just-in-time admin request (PIM, LAPS, a Make-Me-Admin flow), or an explicitly elevated step a human approved — never a script silently escalating. A setup that only works because someone left the developer permanently in the local Administrators group has not modeled the boundary; it has bulldozed it, and the next locked-down machine will prove it.
The important distinction is that ownership is not readiness. If a developer cannot clone because the Git group membership is missing, the workstation is still blocked. But the blocker is not an installer failure; it is a named human or institutional handoff.
IdentityAccess.GitGroupMembership
health: Blocked
remediation: ManualOwned
owner: Identity team
evidence: user is not member of product-coreThat is what the setup model should report. "ManualOwned" does not make the situation green. It says who owns the next move, which evidence proves the blocker, and why welcome doctor --fix must not pretend it can repair it automatically. Part IV turns that distinction into the Doctor result model.
The Git Server Is a Physical Boundary Too
Git often gets treated as "just a tool." For onboarding, it is a compound boundary.
To clone the first repository, the developer needs:
- network reachability to the Git server
- DNS resolution
- trusted certificates or SSH host keys
- a created identity
- group membership
- SSH key or token enrollment
- repository authorization
- local Git installed at a supported version
When any one of those fails, the newcomer sees the same symptom: clone does not work.
Setup-as-code should not collapse all of that into one failure bucket. It should run layered probes:
during first clone
verify dns
verify tls or ssh host
verify identity
verify repository permission
clone readiness repository
clone real project repositoryThat sequence is not an implementation detail. It is the domain language of the onboarding boundary.
Boundaries Make Better CI
CI becomes stronger when it knows which world it is testing.
A cloud runner can test a package manager mirror. A container can test SDK installation. A VM can test a workstation image. A real device can test Wi-Fi and corporate certificates. A human workflow can confirm a badge was issued.
Those are not interchangeable.
The useful rule is:
Automate up to the physical boundary.
At the boundary, probe what can be probed.
For what cannot be probed, require named ownership and evidence.This prevents false confidence. A setup pipeline that passes in Docker but has never tested the company certificate store on a real Windows workstation has not proven first-day readiness. It has proven a subset.
The goal is not one magical runner. The goal is a context map.
A boundary you have named is a boundary you can probe or assign — never a surprise on day one.
Test your onboarding.