Our deployment workflow

A deployment is not just the moment code reaches a server. It is the path from an idea to a public change. For us, that path usually starts in Git, passes through a preview environment, runs the production build, and only reaches the public site after the change has survived both automated checks and human review.

The goal is simple: move uncertainty earlier.

Meaningful work starts on a branch

A substantial feature should not be assembled directly on the production branch. A branch gives the work a boundary. The route changes, content files, styles, metadata helpers, scripts, and supporting infrastructure for one feature can evolve together without turning production into a scratchpad.

The documentation system you are reading was built this way. The initial route framework, MDX content, sitemap integration, navigation links, and audit changes were all kept on a staging branch while the structure was being evaluated. That is not a special case.

It is the workflow we want for meaningful site changes.

The branch should be complete enough to build

A branch is not useful merely because it contains code. The application still needs to compile as a production artifact. The build catches problems that local development may not expose cleanly:

• missing imports
• invalid route assumptions
• bad MDX syntax
• server and client boundary mistakes
• unsupported configuration
• broken static generation
• content parsing failures

A development server is designed to help us iterate. A production build is designed to tell us whether the release can actually exist. We want both.

The preview deployment gives the branch a real environment

Once the branch is deployable, a preview URL lets us inspect the actual application. That matters because screenshots do not test routing. Design mockups do not test keyboard behavior. A local browser does not fully reproduce the deployment environment somebody else will use.

The preview can be opened on multiple devices, shared with a reviewer, and tested like a website rather than a source tree. Read Why preview and production are treated as different systems for the environment distinction.

Preview does not mean public

The preview should behave realistically without becoming another indexed copy of the site. Several of our production repos use environment-aware robots behavior so nonproduction deployments automatically receive noindex treatment. One applies the rule at both the metadata layer and the HTTP response layer.

That is documented in Why preview deployments are explicitly noindex.

Automated audits protect the technical floor

A successful framework build does not prove the site is ready. The connectrader site runs an additional post-build audit over the generated public pages. The audit checks things the framework build does not consider errors:

• heading structure
• exactly one H1
• one main landmark
• titles and descriptions
• canonical URLs
• robots state
• Open Graph metadata
• Twitter metadata
• image alt attributes
• JSON-LD validity and expected schema types
• internal links to rendered routes
• missing referenced images
• robots.txt directives
• sitemap modification dates

That is a different class of validation. The application can compile while the canonical is wrong. The post-build audit exists for that gap.

Human review still matters

Automated checks cannot decide whether the page feels right. We still inspect responsive behavior, copy wrapping, image crops, navigation, forms, modal behavior, spacing, visual hierarchy, and overall coherence. A page can satisfy every technical rule and still be awkward. The build protects the floor.

Human review judges the experience above it.

Production should be a promotion, not an experiment

By the time the work reaches the production branch, the main questions should already have answers. Does it build? Does it render? Does the content exist? Do the routes resolve? Does it work on mobile? Are the metadata and indexing rules correct?

Did somebody look at the actual preview? Production should not be the first environment where we learn those things.

Git makes rollback intelligible

A version-controlled deployment has another advantage. If a release introduces a serious problem, we know which commit changed the site. We can compare it with the prior state, revert the relevant work, or deploy a known earlier commit. That is much safer than trying to remember which settings were clicked inside a live visual editor.

Environment variables remain outside source

The codebase should describe the application. Secrets and environment-specific credentials should not be committed with it. Deployment environments provide those values to the server code that needs them. That keeps the repository transferable without turning it into a credential archive.

The workflow improves architecture

Reproducible deployment puts pressure on the codebase in useful ways. If a project only works after one developer performs five undocumented manual steps, the deployment workflow exposes that weakness. If a branch cannot run independently because production state is assumed everywhere, the preview exposes that weakness.

If a content change requires editing a live database by hand, the release history becomes incomplete. We prefer systems where a known repository state can produce a known deployment.

The release is not the end

After production, we still watch for problems. Analytics can reveal broken paths. Search Console can reveal indexing changes. Runtime logs can reveal errors. Users can reveal viewport and interaction cases we did not predict. The difference is that those observations feed back into the system.

When a failure is repeatable, we try to make it harder to repeat. That is covered in Why regression prevention is part of the engineering. A good deployment workflow does not promise that bugs never ship. It gives us a disciplined way to find them earlier, understand them faster, and make the next release safer.