Preface
Goal: Deploy SSG manually without CI/CD, utilizing git refs feature.
How about deploying SSG without third party CI/CD ? Sure, you can deploy manually, using only your git client on local PC, or notebook, or whatever you call your workstation.
The Challenge
It is common for SSG user to have build directory such as:
_site
or public
or dist
or output
,
or whatever you SSG configuration setup is.
How do I write from
subdirectory _site
in local master
branch,
into root directory in remote gh-pages
branch ?
Example
I’m using Eleventy SSG as an example. It is still rare that people using Eleventy. But do not worry. The example should be easy to follow.
Hypotethically, this example also applied for other SSG as well, such as: Jekyll, Hugo, Hexo, or Pelican.
However, this article is only an example of, how generated can be pushed manually. The methods described here is not recommended for daily use.
Manual CI/CD is not recommended for daily use.
1: Understanding Refs
In the end of this article, I’m using git refs
, to avoid git checkout
.
Making your step, one line shorter.
What is this git refs
anyway?
The official documentation is here:
If you ever have any git repository,
you can check in your .git/config
.
Now you know that you can push directly from a branch to another branch, even though the branch does not exist yet.
Tale of Two Branches
Using the most common workflow for SSG in github, there are two branches,
master
branch for source, andgh-pages
branch for generated site.
We are going to use this scheme.
Two Directories.
Imagine that we have two directories for each
-
ssg-repositories
containingmaster
branch for source code. -
ssg-site
for generated site aka build code.
Notice that both are using master
branch.
Since we can push directly from master
branch to gh-pages
branch,
we can do this from ssg-site
, and our job is done just like that.
$ git push origin master:refs/heads/gh-pages --force
2: Prepare Your Repository
Now, it is a good time to practice with example, so you can have more understanding.
Directory
I use Eleventy as an example SSG. You may use other.
$ mkdir 11ty-repository
$ cd 11ty-repository
Git Remote
Then the git
part.
$ git init
Initialized empty Git repository in /media/Works/repository/test/11ty-repository/.git/
$ git remote add origin git@github.com:epsi-rns/manual-11ty.git
$ git remote -v
origin git@github.com:epsi-rns/manual-11ty.git (fetch)
origin git@github.com:epsi-rns/manual-11ty.git (push)
SSG Source Code
Continue to the SSG source part.
I have already had a ready to use Eleventy Source,
in a directory named 11ty-example
.
$ cp -r ../11ty-example/. .
$ ls
assets package.json sass
Gruntfile.js README.md src
First Commit
Now go back to git
part.
Assuming that all the reader here already get used with git
command,
I use --quiet
parameter, so that the example would not go too long,
unnecessary lines.
$ git add --all
$ git commit -m "Master: First Commit" --quiet
$ git push -u origin master --quiet
This should be self explanatory.
More recent github using main
instead of master
.
Master Branch in Github Repository
Remember that, this is the master
branch,
that contain the source code.
It is only containing one commit.
The first commit
.
3: Generate Build
Since I use Eleventy, this is the example command. You may use other command for Jekyll, Hexo, Hugo, or Pelican.
Eleventy Build
$ npm install
$ npx eleventy
$ npx eleventy serve
...
Copied 1 item and Processed 47 files in 1.67 seconds (35.5ms each)
Watching…
[Browsersync] Access URLs:
--------------------------------------
Local: http://localhost:8080
External: http://192.168.1.223:8080
--------------------------------------
UI: http://localhost:3001
UI External: http://localhost:3001
--------------------------------------
[Browsersync] Serving files from: _site/_eleventy_redirect
Build Directory
Consider check the generated files as result of this build process.
$ ls _site
assets feed lyrics posts tags
_eleventy_redirect index.html pages quotes
For any SSG user, this must be also self explanatory.
Now we have the build code.
4: Build Directory
Now it is a good time to remind you the main question.
How do I write from
subdirectory _site
in local master
branch,
into root directory in remote gh-pages
branch ?
Copy Generated Site
Consider make a new directory without any git
.
We will setup git
later.
$ cd ..
$ mkdir 11ty-site
$ cd 11ty-site
Then copy the generated one into this newbuild directory.
$ cp -a ../11ty-repository/_site/* .
$ ls
assets feed lyrics posts tags
_eleventy_redirect index.html pages quotes
Setup Git
We must setup new git
in this directory.
Notice that this git
here is not related at all,
with previous git
directory.
Both are different git
.
$ git init
$ git remote add origin git@github.com:epsi-rns/manual-11ty.git
$ git add .
$ git commit -m "Update at $(date)" --quiet
$ git log | cat
commit b232faa3e83f4ef94b4c1b74d9b5683f6a1a1d66
Author: epsi sayidina <epsi.rns@gmail.com>
Date: Wed Mar 25 20:04:13 2020 +0700
Update at Wed 25 Mar 2020 08:04:13 PM WIB
5: Push To Github Pages
Consider git push
directly to gh-pages
.
Directly
Why this would be failed.
$ git push origin gh-pages --force
Because you haven’t setup gh-pages
branch yet.
Using Checkout
The solution is simply to do git checkout -b
before git push
.
$ git checkout -b gh-pages
Switched to a new branch 'gh-pages'
$ git add .
$ git commit -m "Update at $(date)" --quiet
$ git push -u origin gh-pages --force
Enumerating objects: 130, done.
Counting objects: 100% (130/130), done.
Delta compression using up to 2 threads
Compressing objects: 100% (83/83), done.
Writing objects: 100% (130/130), 311.83 KiB | 896.00 KiB/s, done.
Total 130 (delta 43), reused 0 (delta 0)
remote: Resolving deltas: 100% (43/43), done.
To github.com:epsi-rns/manual-11ty.git
+ 7837478...4cc23b9 gh-pages -> gh-pages (forced update)
Branch 'gh-pages' set up to track remote branch 'gh-pages' from 'origin'.
Using Refspec
Switching branches, then switching back, in manual work is error prone.
You can avoid checkout
,
and shorter the process with this source:target
namespace,
such asmaster:refs/heads/gh-pages
, as shown below.
$ git push origin master:refs/heads/gh-pages --force
Enumerating objects: 130, done.
Counting objects: 100% (130/130), done.
Delta compression using up to 2 threads
Compressing objects: 100% (83/83), done.
Writing objects: 100% (130/130), 311.83 KiB | 1.08 MiB/s, done.
Total 130 (delta 43), reused 0 (delta 0)
remote: Resolving deltas: 100% (43/43), done.
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote: https://github.com/epsi-rns/manual-11ty/pull/new/gh-pages
remote:
To github.com:epsi-rns/manual-11ty.git
* [new branch] master -> gh-pages
gh-pages Branch in Github Repository
The result of the git push
should be in repository by now.
Remember that, this is the gh-pages
branch,
that contain the build code.
Live Site Preview
The github pages will render the site based on this build code.
You can enjoy the preview at:
What is Next ?
Done with these steps. Now it is time to relax, use the easier step, using automation.
Consider continue reading [ CI/CD - Zeit Now ]. Start from easy deploying. Zeit Now step by step.