When the pipeline is green and the site is still unreachable

The pull request was green, deployed, and still impossible to review. The blocker was not code; it was a missing customer-owned DNS record, which meant the dev site existed everywhere except at the URL anyone needed to test. I was looking at a frontend build with a functioning CI/CD pipeline and a dev instance that could not be reached, validated, or trusted. That is the gap a deployment scoping checklist is built to close: code that cannot be accessed in the target environment is still mostly an intention.

The awkward boundary where software becomes real

The uncomfortable part was not that DNS was missing. Missing DNS is ordinary. The uncomfortable part was that our usual language made it sound peripheral.

We had several development properties in play: multiple customer properties serving different user audiences. The frontend work for the storefront had a CI/CD pipeline. It could produce a deployed instance. From a narrow engineering view, that sounds close to done.

From a field delivery view, it was not close enough.

The PR could not move forward until the customer team added the DNS entry for https://app.dev.internal.example/. Without that, nobody could reach the deployed site through the intended dev URL. Without the intended URL, validation would drift into approximations: internal previews, direct platform URLs, screenshots, local builds, and the other substitutes engineers reach for when the real path is unavailable.

Those substitutes are useful while building. They are poor merge gates.

The practical decision: do not merge yet. Ask the customer infrastructure owner to create the DNS record, then validate the deployed instance through the same style of URL that downstream users and systems would use. Only after that should the PR move forward.

Why a deployment scoping checklist catches what CI does not

CI answers a bounded question: did this code pass the checks we wired into this repository?

A deployment scoping checklist answers a wider question: can this change be exercised in the environment where it is supposed to matter?

Confusing those two questions is how teams end up with a technically deployed artifact and no credible way to validate it.

For this work, the checklist needed to name five things explicitly:

A green deployment pipeline proves that an artifact moved from source control to hosting. It cannot prove that customer-controlled infrastructure routes to it, that the agreed URL is live, or that the right people can test it.

The mechanism under the paperwork

DNS sounds like plumbing, so teams mentally file it under operations. In a customer environment, it is also a coordination protocol. And in this case, one concrete failure path illustrates why.

Suppose validation happens against a direct hosting URL instead of the intended dev domain. The build passes, the page loads. What the direct URL does not exercise: authentication redirects configured to expect the customer's dev subdomain, cookies scoped to that domain, CSP headers tuned to the expected origin, CORS allowlists keyed to the agreed URL, and any network allowlist rules that only permit the customer-controlled hostname. A reviewer approves the PR. Later, after merge, the auth flow silently fails in the real dev environment because the redirect target never matched. The defect was present the whole time; the wrong validation URL simply never triggered it.

That failure path is why dev DNS is not a follow-up item.

A dev property crosses several distinct ownership layers:

Application layer. The frontend builds, deploys, and serves the right version. This is what product engineers track. It lives in the repository, the pipeline, and the hosting platform.

Customer infrastructure layer. The customer owns the domain or subdomain. They may own the DNS zone, certificate policy, proxy rules, allowlists, or internal routing conventions. A delivery team can request the change, but cannot make it directly.

Validation layer. The field team needs a stable URL that represents the intended environment. Authentication callbacks, cookie domains, content security rules, CORS behavior, network allowlists, and stakeholder testing can all behave differently when the URL changes.

The stack matters because a failure in the routing layer can look like a delivery failure, and a delivery failure can be masked by testing through the wrong URL. If the checklist does nothing else, it should stop people from debugging the application before they have verified the path to it.

Deployment scoping checklist for field teams

Here is the checklist I wish more teams used before calling a dev deployment ready for review. The goal is not process furniture; it is to surface the thing that will block the merge at 4:43 p.m.

Name every reachable property

For this work, the dev estate was not a single app. It included multiple properties, each with a distinct audience and validation surface:

This naming step seems obvious until it is skipped. Then the team has a deployed frontend and a vague sentence like "the dev site is somewhere." Somewhere is not an environment.

Separate deployed from reachable

A pipeline can be done while the environment is still not usable. There is no shame in that; there is only risk in pretending otherwise.

Put DNS on the critical path early

Customer-owned infrastructure runs on its own cadence: ticket queues, access controls, security review, change windows, and people who are quite reasonably doing other jobs. Request the DNS entry before the PR is waiting on it.

For this project, the right move was to ask the customer team for the DNS entry and hold the PR until the site could be accessed and tested. The difference was between merging a hopeful artifact and merging a verified one.

A deployed instance without the intended route is a rehearsal, not a release candidate.

Assign validation ownership

A common failure mode is the passive sentence: "once DNS is done, testing can happen." That sentence contains no owner. It should not survive review.

The checklist needs a named validation owner for each environment:

The evidence should be lightweight. This is not a compliance ceremony; it is a way to prevent everyone from assuming someone else clicked the link.

What I considered and rejected

The tempting option was to merge after the pipeline succeeded and treat DNS as a follow-up. That would have kept the code moving and made the board look cleaner. It also would have moved uncertainty into the branch that other work depends on.

I rejected that because the PR was blocked by the absence of the real validation path, not a cosmetic concern. If the deployed site cannot be reached at the intended dev URL, then any downstream approval is conditional on infrastructure that has not been proven.

Another option was to validate against a direct hosting URL. That works for early smoke testing, but it is not equivalent when the intended dev domain affects auth redirects, cookies, headers, routing, or stakeholder access. If those are in scope, direct-host validation is a partial signal.

A third option was to create a temporary workaround under a domain the delivery team controlled. I have used that pattern before, and it can be the right move when customer DNS is slow and the feature needs early feedback. In this case, it would not have answered the merge question. The customer-owned dev URL was part of the environment contract, so the workaround would have been a detour, not a gate.

The cost of being strict

Holding the merge had a cost. It delayed the PR and required telling people that a pipeline-complete change was not yet merge-ready.

Teams can overuse this kind of gate and turn every environment detail into a bureaucratic parking brake. A dev DNS issue blocks merge only when the intended URL is part of the validation contract. If the change is purely internal, isolated behind a feature flag, or already covered by an equivalent deployed environment, blocking is unnecessary.

The useful rule is narrower: block when the missing environment piece prevents the team from exercising the risk the PR is supposed to retire.

In this case, the risk was whether the deployed frontend actually worked in the customer dev environment. DNS was not trivia; it was the doorway.

Field delivery versus generic DevOps

Generic DevOps advice tends to say, automate the pipeline. That advice is fine as far as it goes. It stops too early for field work.

Field delivery lives in the gap between software that exists and software that the customer can safely use. That gap includes access, ownership, naming, data, network paths, validation rituals, and the local politics of who can change what. It is also where many deployments become real or quietly become fiction.

The reusable artifact from this incident is not a clever script. It is a scoping habit:

This is the part of delivery that feels too small to formalize until it blocks you.

FAQ

Why should dev DNS block a merge?

Dev DNS blocks a merge when the intended dev URL is required to validate the change. If reviewers cannot reach the deployed instance through the agreed environment route, the team has not proven the behavior it is relying on.

What belongs in a deployment scoping checklist?

A deployment scoping checklist includes customer-owned DNS, environment URLs, CI/CD status, merge gates, validation owners, and the evidence needed to move forward. The point is to make environment dependencies visible before they become late-stage blockers.

Is a direct hosting URL good enough for testing?

Sometimes it is good enough for early smoke testing. It is not enough when the real dev domain affects auth, cookies, routing, access control, or stakeholder review.

Who owns customer DNS coordination?

The customer infrastructure team owns the DNS change, but the field delivery team owns making the dependency explicit, tracking it, and tying it to the merge gate.

How do I avoid turning this into process overhead?

Keep the checklist short and attach it to real gates. If an item does not affect reachability, validation, or merge readiness, it does not belong there.