My personal static blog is hosted on Github. I used Hexo before, but as its complicated package dependence and cumbersome deployment process, I have to encapsulate the whole deployment environment into Docker image for rapid deployment, but it was still too complex. Now I switch to Hugo which is faster, simpler.
This article documents how to automatically synchronize blog contents generated by Hugo to Github through Travis CI.
New: I have migrated my blog from Github to GitLab on May 24, 2019 due to GitHub and Export Controls. Blog is Migrating Personal Hugo Static Blog From GitHub Pages To GitLab Pages.
This article is one of my personal static blog build series:
- Using Hugo and Travis CI To Deploy Blog To Github Pages Automatically
- Using Cloudflare Free SSL In GitHub Pages With Custom Domain
- Setting Up Slack Build Notification in Travis CI for Github Project
Attention: The following operation process will not involve account registration, Git configuration.
Official Docs
The relevant operations in this document are based on the official document as the operation guides:
- Github
- Hugo
- Travis CI
GitHub Pages Limits
GitHub Pages is a static site hosting service designed to host your personal, organization, or project pages directly from a GitHub repository.
GitHub Pages sites are subject to the following usage limits:
- GitHub Pages source repositories have a recommended limit of 1GB.
- Published GitHub Pages sites may be no larger than 1 GB.
- GitHub Pages sites have a soft bandwidth limit of 100GB per month.
- GitHub Pages sites have a soft limit of 10 builds per hour.
More details in official document What is GitHub Pages?.
Prerequisite
- Registering a Github account;
- Registering a Travis CI account (login with Github account);
- Installing
git
,hugo
in your system; - Personal domain (optional, here my domain is
axdlog.com
);
Hugo Installation
- Github url: https://github.com/gohugoio/hugo
- Downloading page: https://github.com/gohugoio/hugo/releases
- Release Info API: https://api.github.com/repos/gohugoio/hugo/releases/latest
Install Hugo is the official installation document of Hugo. If you’re using GNU/Linux, you may consider using my Python script to install it quickly.
Current release version info
|
|
Python Script
Python script url is https://axdlog.com/script/hugo.py, it is used to install or upgrade Hugo on GNU/Linux.
Operating process
|
|
Create A New Site
You can reference official document Get Started、Quick Start to know how to create a new site through Hugo.
If this is your first time using Hugo and you’ve already installed Hugo on your machine, we recommend the quick start.
Here I name the site to quickstart
(it is just the directory name, not the final site name).
|
|
Directory structure generated by Hugo:
|
|
Attention: These files are not the final blog contents, they are just used to generate the blog contents.
Directory content
is used to store your blog file (Markdown file).
If you wanna preview the final effect, just executing command hugo server
to set up a local server which is listening port 1313
. And opening the link in your browser.
|
|
Executing command hugo
in your project directory, it will generate a directory named public
. This directory contains the final blog contents. What you need to do is push all the files in this directory to the branch master
of your GitHub repository.
The demonstration process is as follows:
|
|
Github Repository Operation
Attention: The handling ideas and operations of this section are very important. Git setting procedure in official documents GitHub Help、Git Cheat Sheets.
If you use GitHub Pages to host blog, you need to create a repository named <username>.github.io
. Then putting the files generated by Hugo to the branch master
of this repository.
I create 2 branches via command git checkout --orphan
to store source files and blog contents in directory public
separately.
- branch
code
stores source files; - branch
master
stores blog contents in directorypublic
;
Attention please, this method is different from official document Configuring a publishing source for GitHub Pages.
Create Empty Repository
My GitHub account is MaxdSre
, so I need to create a repository named maxdsre.github.io
.
After creating the repository, it will prompts
or create a new repository on the command line
|
|
or push an existing repository from the command line
|
|
Pushing Repository
There are 4 steps:
- Initializing Git repository via command
git init
in project directory; - Creating branch
code
, pushing source files to remote repository; - Executing command
hugo
to generatepublic
directory; Transferring all the files in this directory to another temporary directory, empty project directory, then move the files store in temporary directory back to project directory; - Creating branch
master
via commandgit checkout --orphan
, then pushing all files store in current directory to remote repository.
Entering the target directory (here is /PATH/quickstart/
), then executing the following commands in sequence.
Branch code
|
|
Branch master
Executing command hugo
in project directly to generate directly public
. If you wanna check the branch info of this repository, just executing command git branch -a
.
|
|
Branch image
This section is optional. In order to store images in GitHub directly, I create the third branch image
. All images used in blog will be saved in this branch.
Notice: GitHub provides 1 GB storage space for every repository, single file must less then 100 MB in size, more details in official document File and repository size limitations。
|
|
Switching branch
If you wanna switch your local branch to remote branch remotes/origin/image
, you may consider executing the following command
|
|
Demonstration example
|
|
Here remote default branch is code
, if you wanna change to branch master
|
|
Deleting branch
Deleting branches has three types: remote branch, local branch, local remote-tracking branch, more details in How do I delete a Git branch both locally and remotely?.
|
|
Travis CI Configuration
GitHub Pages Deployment is the official document of Travis CI。
Github Access Token Generation
You’ll need to generate a personal access token with the public_repo or repo scope (repo is required for private repositories). Since the token should be private, you’ll want to pass it to Travis securely in your repository settings or via encrypted variables in .travis.yml.
Generating personal access tokens
in GitHub Pages Developer settings. If it is a private repository, choose repo
. Otherwise, just choose public_repo
. Here I choose public_repo
, repo:status
, repo_deployment
.
The length of the generated token is 40, please keep is private.
Environment Variables Setting
Generated token
is used in Travis CI, the page url of target repository in Travis CI is https://travis-ci.org/MaxdSre/maxdsre.github.io/settings.
Don’t forget to check Build only if .travis.yml is present
, Build pushed branches
, Build pushed pull requests
.
The default name of token
defined in official document GitHub Pages Deployment is GITHUB_TOKEN
, this document alse lists other directives.
Notice that the values are not escaped when your builds are executed. Special characters (for bash) should be escaped accordingly.
Defining variables, it will be used in file .travis.yml
latter.
Environment Variables | Value |
---|---|
CNAME_URL | axdlog.com |
GITHUB_USERNAME | MaxdSre |
GITHUB_EMAIL | [email protected] (pseudo value) |
GITHUB_TOKEN | 75e8b7y318ebf48df0bc35cp4affd79e167b2489 (pseudo value) |
.travis.yml directives
Hugo is written by Golang. If I chose language: go
in .travis.yml
, the process of build Golang environment costed too much time (a few minutes).
I find someone use Python to deploy successfully, then chose Python as operation environment. As the containers of Travis CI is based on Ubuntu, I can use command dpkg
, apt-get
, but it needs sudo
privilege.
As Python failed to build frequently, because GitHub forbided HTTP request from Travis container. I solve this problem via tor
proxy.
The final code is as follow
Python
|
|
Golang (deprecated)
|
|
Writing it into file .travis.yml
, and push file .travis.yml
to the branch code
of remote repository.
Continuous Integration
After all operations are finished. If you push your changed source file to branch code
. Travis CI will automatically execute directives defined in file .travis.yml
, then pushing the generated blog contents to branch master
.
Deploying log
References
- Continuous Integration of Hugo Website using Travis CI and Github
- Travis continuous delivery
- How to create a website like freshswift.net using Hugo, Travis CI, and GitHub Pages
- GitLab CI remove priority zero from Hugo sitemap
- Deploy Hugo site to Github Pages with Travis CI
Change logs
- 2018.04.11 00:20 Wed America/Boston
- first draft
- 2018.07.11 12:20 Wed America/Boston
- add python script for hugo installation
- 2018.08.03 08:44 Fri Asia/Shanghai
- add switch branch
- 2018.12.04 11:46 Tue America/Boston
- use Golang in travis
- 2019.01.30 09:38 Wed America/Boston
- still use Python in travis, short time consuming
- 2019.04.05 22:44 Fri America/Boston
- update hugo version to
v0.54.0
- update hugo version to
- 2019.04.26 12:33 Fri America/Boston
- update hugo version to
v0.55.4
- update hugo version to
- 2019.05.02 11:26 Thu America/Boston
- update hugo version to
v0.55.5
- update hugo version to
- 2019.05.07 15:47 Tue America/Boston
- add GitHub Pages limits introduction
- 2020.12.26 20:28 Thu America/Boston
- update hugo version to
v0.79.1
, update Python script url
- update hugo version to