A dependable static website deployment connects a reviewed Git revision to the exact files visitors receive. That connection should remain understandable after a failed build, a broken link, or an urgent correction. The key is to define a repeatable process: select a revision, build its output, inspect the result, publish a complete release, and verify the public site.

This process works for a small HTML project and scales to a generated documentation site. The tools can vary, but the release questions stay similar. Which commit is live? What changed? Where is the previous working artifact? Who can publish? Answer them early, alongside the repository conventions described in our Git file workflow hub.

Confirm that the output is truly static

A static host serves files such as HTML, CSS, JavaScript, images, and downloadable documents. Browser JavaScript can add interaction or call an API, but that does not create a private server runtime on the static host. WordPress PHP, a Django application server, database access, and protected business logic need suitable backend services unless their output has been exported into static files.

List every feature that crosses this boundary. Search may use a local index or a hosted service. A form needs a real submission destination. Authentication must protect the data service, not simply hide a button. Mark any disconnected feature honestly in a prototype, and connect it before describing the production website as functional.

Write a short release contract

Record the source branch, build command, required runtime version, dependency installation method, output directory, and publication destination. Include the site's base URL and whether it lives at the domain root or beneath a project path. These details prevent a successful local build from silently generating links for the wrong location.

Define which files may be published. For a generated site, the answer is normally the finished output directory. Repository metadata, private source material, local environment files, dependency caches, and backup archives should remain outside it. For a plain HTML site with no build step, prepare an explicit publication directory instead of assuming the repository root contains only public files.

Make the build repeatable

Commit the dependency lockfile and record the runtime used to produce a release. Build from a clean checkout so untracked files on one developer's laptop cannot become invisible requirements. Ensure the process stops when an installation, build, or validation step fails. A later successful copy should never conceal an earlier failed build.

Choose a specific commit for the release and save its identifier with the resulting artifact. Also preserve the build configuration and enough dependency information to investigate differences later. A timestamp alone does not tell you which source produced the deployed files. A dependency update deserves its own review when it changes output or introduces new build behavior.

For a local review, these read-only checks help identify the current revision and obvious workspace problems. They do not replace building or reviewing the website:

git status --short
git rev-parse HEAD
git diff --check

Separate building from publishing

Treat the generated output as a release artifact that can be inspected before publication. The GitHub Pages custom workflow documentation provides one example of distinct build, artifact, and deployment stages. Other hosts can use the same design even when their configuration and permission names differ.

Review permissions by job. A build usually needs to read source; publication needs authority over a destination. Keep that authority limited to the required site or environment. Treat third-party workflow components as executable dependencies, pin them to reviewed immutable revisions when supported, and maintain an update process. Avoid giving untrusted contribution code access to production secrets.

Build artifacts also cross a trust boundary. A privileged deployment job should know which trusted workflow produced the artifact and which approved revision it represents. A plausible filename is not proof of origin. Keep deployment triggers understandable, especially when one workflow starts another.

Inspect the website as visitors will use it

Preview the generated files through a local or temporary web server rather than relying only on opening an HTML file directly. Web serving exposes route behavior, asset paths, and content-type problems that a filesystem preview may hide. Match the production base path during the preview when practical.

Use a concise set of meaningful checks:

  • Open the homepage, a nested content page, and a deliberately nonexistent URL.
  • Follow navigation and footer links; verify that category links reach useful destinations.
  • Inspect a narrow mobile viewport, keyboard navigation, and visible focus states.
  • Confirm that CSS, scripts, fonts, and images load without console or network errors.
  • Test each interactive feature, including its empty, invalid-input, and unavailable-service states.
  • Review page titles, canonical URLs, sitemap paths, and any production indexing directives.

Protect previews containing private material with actual access controls. A difficult-to-guess URL or an indexing directive does not authenticate visitors. Conversely, check that a preview's indexing restrictions do not accidentally ship with the public release.

Publish a complete release

Uploading files directly over a live directory can expose an intermediate mixture of versions. Prefer a host's complete-release deployment mechanism or a server arrangement that prepares a separate release directory and switches traffic after validation. Keep the activation step small and preserve the previous release until the new one has passed its checks.

Prevent competing deployments from publishing in the wrong order. Two builds may finish at different times even when their commits arrived sequentially. Use one controlled publication queue or verify that the release still represents the intended production revision before activation. Document whether a newer request cancels an older one or waits for it.

If your preview and production environments require different embedded configuration, acknowledge that promoting source may require a new build. Otherwise, promote the already tested artifact. Avoid quietly rebuilding with changed dependencies after approval and assuming the result is identical.

Plan assets and caching together

Use content-versioned filenames for assets that receive long cache lifetimes, and generate HTML that references those exact filenames. Keep entry pages on a freshness policy appropriate to how quickly updates must appear. Publishing new files at the origin does not necessarily remove older responses already held by browsers or a CDN.

Retain assets needed by recently published HTML. A visitor can have an older document open when a new release becomes live; deleting all prior scripts immediately may break that session. Set retention based on your cache policy and release pattern. Our Nginx and CDN deployment guide explains how origin behavior and shared caches interact.

Make rollback a practiced action

Keep the last known working artifact and its commit identifier. Rehearse how to reactivate it in a test destination. Reverting source and rebuilding can be useful, but it depends on a functioning build environment and available dependencies. A retained artifact gives you another recovery option when those services are part of the incident.

After activation, check the public domain rather than only the deployment dashboard. Confirm a visible change, a nested page, an asset, and an expected error response. If the website uses APIs, verify that the restored frontend remains compatible with their current behavior. Record the outcome and the release identifier.

Assign ownership to failed releases

A useful deployment notification identifies the site, revision, stage, and next person responsible. Distinguish a build failure from a publication failure and a public-site check failure. Each has a different recovery path. Keep enough diagnostic information to investigate while preventing credentials or private content from appearing in logs.

Write down when the team should repair forward and when it should restore the previous artifact. Use the user impact and the availability of a tested fix to make that decision. A release process is easier to operate when the response does not have to be invented during an incident.

Common mistakes

The most damaging shortcuts are publishing the wrong directory, placing secrets into frontend bundles, assuming every route should return the homepage, and declaring success when an upload finishes. Add a specific check for each risk that applies to your project. More automation helps when it catches a real failure mode; it does not replace understanding what the website should do.

Frequently asked questions

Should generated files be committed?

Follow the host and project workflow. Some publication methods use an output branch; others deploy a build artifact. Keep generated content clearly distinguished from source so reviews remain useful.

Can a private repository publish a public site?

Repository visibility and website access are separate decisions. Check the chosen host's supported configuration and review the final artifact as public material whenever the website is intended for public access.

Is a successful build enough?

No. A build can finish while generating broken links, incorrect metadata, or disconnected forms. Inspect output, test important behavior, and check the public release.

Finish with an observable release

A good deployment ends with a known artifact serving correctly at the intended address and a clear path back to a working version. Keep the process documented alongside the project, then improve it when an actual failure reveals a missing check.