The benson.vc site uses GitHub Pages for hosting, with automated deployments via GitHub Actions. Every push to the main branch triggers a new deployment.
How it works
The deployment process is fully automated through a GitHub Actions workflow:
- Code is pushed to the
main branch
- GitHub Actions triggers the workflow
- Hugo builds the site with minification
- Static files are deployed to the
gh-pages branch
- GitHub Pages serves the site from the
gh-pages branch
GitHub Actions workflow
The workflow is defined in .github/workflows/gh-pages.yml:
name: GitHub Pages
on:
push:
branches:
- main
jobs:
build-deploy:
runs-on: ubuntu-latest
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
steps:
- name: Checkout
uses: actions/checkout@v3
with:
submodules: true
fetch-depth: 0
- name: Setup Hugo
uses: peaceiris/actions-hugo@v2
with:
hugo-version: "latest"
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
if: ${{ github.ref == 'refs/heads/main' }}
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_branch: gh-pages
publish_dir: ./public
Deployment steps
The workflow performs these steps:
Checkout repository
Clones the repository including submodules (for the Hugo theme).
Setup Hugo
Installs the latest version of Hugo in the CI environment.
Build the site
Runs hugo --minify to generate optimized static files in the public/ directory.
Deploy to gh-pages
Pushes the contents of public/ to the gh-pages branch using the built-in GitHub token.
Repository settings
To enable GitHub Pages for your repository:
Navigate to Settings
Go to your GitHub repository and click on Settings.
Open Pages settings
In the left sidebar, click Pages under the “Code and automation” section.
Configure the source
Under “Build and deployment”, set:
- Source: Deploy from a branch
- Branch:
gh-pages
- Folder:
/ (root)
Save and wait
GitHub Pages will deploy your site. The URL will be shown at the top of the Pages settings.
The gh-pages branch is managed entirely by the GitHub Actions workflow. Do not manually commit to this branch, as your changes will be overwritten on the next deployment.
Monitoring deployments
You can monitor deployment status in several ways:
- Actions tab: View workflow runs and logs in the repository’s Actions tab
- Commit status: Check marks next to commits indicate successful deployments
- Pages settings: Shows the current deployment status and URL
Troubleshooting
If your deployment fails:
- Check the workflow logs in the Actions tab for error messages
- Verify that the
gh-pages branch exists and is set as the Pages source
- Ensure your Hugo build succeeds locally with
hugo --minify
- Confirm that the CNAME file is present in
static/CNAME
Manual deployment
If needed, you can manually trigger a deployment by pushing to the main branch:
git add .
git commit -m "Trigger deployment"
git push origin main
Next steps
To use a custom domain with your GitHub Pages site, see Setting up a custom domain.