Deploying a static website from Git to free cloud hosting is usually a repeatable process: connect a repository, identify the build output, publish it, and verify the result. This guide explains that workflow for HTML, CSS, JavaScript, and common static-site frameworks, while showing what to monitor after launch so each deployment is easier to troubleshoot, review, and roll back.
Overview
A static website is delivered to visitors as pre-built files rather than generated by a server for every request. A simple project may contain index.html, a stylesheet, JavaScript files, and images. A framework-based project may require a build command that transforms source files into a production directory such as dist, build, or public.
Free cloud hosting platforms commonly let you deploy website files from a Git repository. The exact dashboard labels, supported Git providers, available runtime versions, and usage limits can change, so treat the following as a platform-neutral workflow. Before starting, check the current documentation for your chosen host and confirm which repository providers and build environments it supports.
The central rule is simple: the hosting service must publish the directory that contains the finished site. If that directory is wrong, the deployment can appear successful while returning a blank page, a 404 error, or a page without its styles and scripts.
What to track
1. Repository structure
Start by identifying where the deployable project lives. For a basic site, the repository might look like this:
my-site/
├── index.html
├── styles.css
├── script.js
└── images/
If the project uses a framework or package manager, look for files such as package.json, a lockfile, and a source directory. A typical structure may include src for source code and dist or build for generated files. Note whether the site is at the repository root or inside a subdirectory. This affects both the working directory and the build configuration.
2. Build command and output directory
A plain HTML site may need no build command. In that case, the publish directory is often the repository root, provided it contains index.html. A framework project usually needs two settings:
- Build command: the command that creates the production files, often defined in
package.json. - Output directory: the folder the host should serve after the build finishes.
Do not guess the output folder from the framework name alone. Inspect the project configuration and run the build locally when possible. Afterward, open the generated directory and confirm that it contains an entry HTML file and the referenced assets.
3. Runtime and dependency settings
Record the runtime version and package-manager behavior used by the project. A deployment can fail when the local environment and cloud build environment resolve different dependency versions. Commit the appropriate lockfile when the project uses one, and avoid relying on packages or commands that exist only on your computer.
Keep the build environment limited to what the site needs. A static site should not require production access to a database, private server, or administrative credential. If the host supports selecting a runtime version, choose one compatible with the project and review it whenever the framework or dependencies are upgraded.
4. Environment variables
Separate public configuration from secrets. A public API base URL or analytics identifier may be intended for browser delivery, while private tokens, passwords, and service credentials should never be placed in client-side JavaScript or committed to Git.
List the variables required during the build and distinguish them from variables needed only by a server-side process. Static files expose anything bundled into the browser, even when the value was supplied through a protected build setting. After changing an environment variable, trigger a fresh deployment and verify that the generated site uses the new value.
5. Deployment and verification signals
Track the commit identifier, branch, build status, deploy URL, and the time of each release. A successful build only confirms that the host completed its process; it does not prove that navigation, forms, assets, metadata, or third-party integrations work correctly.
For every deployment, check the homepage, one internal route, the browser console, and the network requests for CSS, JavaScript, fonts, and images. Test both the host-provided URL and, once configured, the custom domain. If you use a custom domain, review the separate custom domain and HTTPS checklist.
Cadence and checkpoints
Use a small preflight checklist before the first deployment and whenever the project changes.
- Confirm the branch: Make sure the deployment points to the intended production branch rather than a temporary feature branch.
- Check the repository: Confirm that the entry file, source files, lockfile, and required configuration are committed.
- Run the build locally: If the project has a build step, run it and inspect the output directory.
- Set the working directory: If the site is in a monorepo or subfolder, configure the directory containing its package and source files.
- Set the build command: Use the project’s documented production command rather than a development server command.
- Set the publish directory: Point the host to the generated directory, or to the repository root for a no-build HTML site.
- Review variables: Add required non-secret build variables and remove obsolete values.
- Deploy a preview: When available, use a branch or pull-request preview to test changes before production.
- Verify the release: Test routes, assets, responsive layout, forms, metadata, and the browser console.
- Record the release: Note the commit, change summary, result, and any follow-up task.
For an active site, review deployment history monthly or quarterly. Monthly checks suit frequently edited projects, while a quarterly review may be adequate for a stable portfolio or brochure site. At each review, confirm that the build still completes, the runtime is supported by the project, preview deployments behave as expected, and the production URL serves the current branch.
After a major framework upgrade, dependency update, repository restructure, or hosting-dashboard change, perform the checklist immediately rather than waiting for the next scheduled review.
How to interpret changes
When a deployment fails, compare the first failing step with the last known-good deployment. This narrows the problem to a configuration change, dependency change, source change, or hosting-environment change.
| Symptom | Likely area | Checks to perform |
|---|---|---|
| Build fails before creating output | Dependencies, runtime, or command | Read the first error, confirm the runtime, inspect the lockfile, and run the same production command locally. |
| Deployment succeeds but shows a 404 | Publish directory or entry file | Confirm that the configured output folder contains index.html and that the host is publishing that folder. |
| Page loads without CSS or JavaScript | Asset paths or base URL | Inspect browser network errors, check absolute versus relative paths, and confirm the framework’s public-path setting. |
| Deep links fail while the homepage works | Routing and fallback behavior | Check whether the site uses client-side routing and whether the host supports the required history fallback or route configuration. |
| Page is blank with no obvious error | Runtime JavaScript or incorrect output | Open the browser console, verify that the deployed files match the latest commit, and inspect the generated HTML and script paths. |
| Old content remains visible | Cache or stale deployment | Confirm the deployment commit, test in a private window, inspect response headers where available, and allow for cache propagation before judging the result. |
Rollback should be deliberate. If the previous deployment is known to work, restore that release or redeploy its commit instead of making several untracked changes at once. Then reproduce the failure in a branch, document the cause, and promote the fix after verification. A rollback restores availability; it does not remove the need to resolve the underlying issue.
For performance-related symptoms, use a repeatable test rather than relying on one visit. Review the website performance audit checklist for a broader examination of assets, loading behavior, and page structure.
When to revisit
Return to this workflow whenever you create a new site, change the production branch, move files, upgrade a framework, alter environment variables, or see a failed deployment. These events can change the build command, output directory, asset paths, or required runtime even when the visible design remains the same.
Schedule a monthly or quarterly review for recurring checks. Refresh the article’s platform-specific notes twice a year, and sooner after a major hosting-platform change. Reconfirm dashboard labels, supported Git providers, runtime choices, build settings, preview behavior, cache controls, rollback options, and security guidance rather than assuming they remain unchanged.
For the next deployment, copy the preflight checklist into your project notes, record the current working configuration, and make one controlled change at a time. If you are starting from a build folder rather than Git, compare this process with the static site hosting deployment guide. For a creator site, the portfolio hosting setup plan can help you extend the same workflow to images and contact forms.
