To deploy a static website with GitHub Pages, put the site in a GitHub repository, choose either branch publishing or a GitHub Actions workflow, and set the published output’s root directory. Branch publishing is the simplest choice for static files or a supported Jekyll site; use Actions when you need a custom build or a generator other than Jekyll. GitHub Pages serves HTML, CSS, and JavaScript—it does not run server-side PHP, Ruby, or Python.
Choose a publishing method
GitHub describes Pages as a static hosting service that takes HTML, CSS, and JavaScript from a repository, optionally runs a build process, and publishes a website. GitHub Docs: What is GitHub Pages?
| Method | Best suited to | Build and output |
|---|---|---|
| Publish from a branch | A simple static directory or the supported Jekyll flow. | Select a branch and either its root or /docs directory as the publishing source. The site files must be in that selected location. |
| GitHub Actions | A custom build process or a static-site generator other than Jekyll. | A workflow builds the site if needed, uploads the generated files as a Pages artifact, then deploys that artifact. The artifact’s top level must contain the site entry file. |
Actions is not necessary just to publish a set of ready-to-serve static files. GitHub explains the available publishing sources in Configuring a publishing source and Using custom workflows with GitHub Pages.
Before you start
- Create or choose a repository containing your website, or the source files from which you will build it.
- If your account or organization uses GitHub Free, the repository must be public to use Pages.
- For an Actions deployment, plan for the generated site’s entry file—usually
index.html—to be at the top level of the uploaded artifact, rather than nested one directory down.
Publish from a branch
- In your repository, open Settings → Pages.
- Under the build and deployment settings, choose the branch containing the site files.
- Choose the publishing directory: the repository root or
/docs, depending on where those files are located. - Save the source setting, then push your site files to the selected branch and directory.
- Check the Pages settings or the repository’s build status for the published site URL and deployment progress.
This route works well when the files are already static or the site uses GitHub’s supported Jekyll flow. If your build needs another generator or custom commands, use an Actions workflow instead. GitHub’s setup steps are in Creating a GitHub Pages site.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstall#1 Best Overall
Deploy a built site with GitHub Actions
- Open the repository’s Settings → Pages and set the publishing source to GitHub Actions.
- Add a workflow file under
.github/workflows/. The workflow should check out the repository, run your build command if the project needs one, upload the generated static output withactions/upload-pages-artifact, and deploy it withactions/deploy-pages. - Give the deployment job the
pages: writeandid-token: writepermissions it needs, and connect it to thegithub-pagesenvironment. - Make the deploy job depend on the build job so deployment runs only after the artifact has been created.
- Push the workflow and site changes to the branch that should trigger deployment. Open the repository’s Actions tab and confirm the build and deployment jobs succeed.
- Visit the deployment URL shown in the run output or on the repository’s Pages settings page. If the build succeeds but the site does not load, check that the artifact contains the entry file at its top level.
GitHub’s custom-workflow guide covers the Pages artifact and deployment setup.
Use the correct site URL and asset paths
The repository name determines whether Pages serves a project site under a repository subpath or an owner’s site at the root of the owner’s github.io domain.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
| Site type | Repository naming | URL pattern |
|---|---|---|
| User or organization site | The repository uses the owner’s github.io name. |
https://owner.github.io/ |
| Project site | The repository can use the project’s name. | https://owner.github.io/repositoryname/ |
On a project site, make sure links to CSS, JavaScript, images, and other pages account for the /repositoryname/ path. Paths that assume the site is at the domain root can work locally but fail after deployment. See GitHub’s Pages overview for the site types and URL patterns.
Add a custom domain (optional)
A custom domain is not required to publish on GitHub Pages. If you want one, first verify domain ownership as GitHub recommends, then add the domain in Settings → Pages and configure the matching DNS records with your domain provider.
Rank #3
- For an apex domain such as
example.com, GitHub documents ALIAS, ANAME, or A records. - For a subdomain such as
www.example.com, use a CNAME record. - Do not use wildcard DNS records: GitHub warns they can expose subdomains to takeover.
- A custom Actions workflow does not require a
CNAMEfile.
Follow GitHub’s custom-domain setup instructions and its explanation of custom domains and Pages to match the record type to your domain.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Fix common deployment problems
- The site is missing or looks stale: Check that Pages points to the branch and directory where you published the files. For Actions, inspect the latest workflow run for failed build or deploy jobs. Confirm the published directory or artifact’s top level contains the entry file. GitHub estimates that a push can take up to 10 minutes to publish; this is an operational estimate, not a guaranteed deadline.
- Assets fail on a project site: Check whether asset and navigation paths include the repository subpath.
- A generator build fails or produces no site: Use Actions for a generator other than Jekyll or a custom build. If publishing prebuilt files from a branch, use GitHub’s documented no-Jekyll route where appropriate.
- A custom domain does not resolve: Confirm the domain is set in Pages settings and that its DNS record matches whether it is an apex domain or subdomain. GitHub estimates DNS changes may take up to 24 hours to propagate.
- HTTPS is not available yet: After configuring a custom domain, GitHub estimates HTTPS may take up to 24 hours to become available.
These timing estimates come from GitHub’s Pages troubleshooting guidance; they are not guarantees.
Quick Recap
Best Value
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
