My personal site/portfolio has always been hosted on Github Pages, but recently I decided to automate my workflow for my site. I opted to give Github Actions a try to implement a CI/CD process, and build and deploy the codebase to the already existing Github Pages Repository (see GH Pages documentation).
The codebase I used for building and deploying with GH Actions is a VueJS app, but you can adjust the workflow to fit your needs or programming language.
The workflow I used is to deploy built code into the root directory of your GH Pages, not in a subdirectory (Application that will be shown on {{Github_username}}.github.io
and not on {{Github_username}}.github.io/myNewApplication
1. Enable Github Actions & init Github workflow
- In the GH repository of the codebase, click on the Actions tab.
- If not enabled yet, in the Github Actions overview, you can opt to use an already existing workflow, or skip and set up a workflow yourself.(I chose to create my own workflow, but this is a preference)
- When selecting a pre-configured workflow, a YAML editor will open with the selected workflow configuration, when opting to create your own, Github will configure a workflow file based on the type of codebase and show you in the YAML editor
- You can give the workflow file a different name based on the process/action you want to run in the action(build, deploy, test,...), change the name to branch-specific information (dev, stage, production), or give it a name of choice
- (I always initialize and commit the workflow file first, before making any changes, added to the repository, by clicking Start Commit and confirming. Again, this is a preference)
- (If not committed yet, you can continue with the next step.
If committed first, you will be returned back to the location of where the
workflow.yml
was added in your repo. To return back to editing the workflow, click Actions, select the latest workflow commit, and click on Workflow file. In this detailed overview, you will be able to change the.yaml
file using the edit button.)
2. Adjust the workflow to fit your needs
To be able to build my Vue codebase and deploy my built code, I used the following workflow.yml
. I added comments to the file to explain all parts of the workflow.
# Name that will define how it shows up in
# your Github Action overview for this repository
name: Build and Deploy
# Defines what events the workflow will listen to in repository
# In this case commits and pull-requests on master-branch
on:
push:
branches: [master]
pull_request:
branches: [master]
# What jobs will run in your workflow -> build_and_deploy
# Jobs can run in parallel or sequentially
jobs:
build_and_deploy:
# Type of runner that this job wil run on -> Linux Ubuntu
runs-on: ubuntu-latest
# Define which node version to use in the runner.
# Use node version 14.15.0, latest Node LTS version
strategy:
matrix:
node-version: [14.15.0]
# Steps that are part of the build_and_deploy job
# Steps represent a sequence of tasks that will be executed
steps:
# Action that will checkout repository so the workflow can
# access the codebase
- uses: actions/checkout@v2
# Action allowing caching of node_modules to improve
# workflow execution time
# {{runner.os}} will use defined runner 'ubuntu-latest'
- name: Cache node_modules
uses: actions/cache@v2
env:
cache-name: cache-node-modules
with:
path: ~/.npm
key: ${{ runner.os }}-build-${{ env.cache-name}}-${{hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-build-${{ env.cache-name }}-
${{ runner.os }}-build-
${{ runner.os }}-
# Sets node environment for use in action
# {{matrix.node-version}} will use Github default Node.js
# version
- name: Node ${{matrix.node-version}}
uses: actions/setup-node@v1
with:
node-version: ${{matrix.node-version}}
# Run npm commands to install NPM packages
- name: Install dependencies
run: npm install
# Run npm build command for Vue project
- name: Build Project
run: npm run build
# Push built code to the upfront created GH pages repo
- name: Pushes to another repository
uses: cpina/github-action-push-to-another-repository@master
env:
# Create and store API_TOKEN_GITHUB in repository
# secrets -> explained later in this article
API_TOKEN_GITHUB: ${{ secrets.API_TOKEN_GITHUB }}
with:
# Define source directory to push from -> Vue default
# built into /dist folder
source-directory: 'dist'
# Set user settings and repository to push to
destination-github-username: '{{Your_Username}}'
destination-repository-name: '{{GH_Pages_Repository}}'
user-email: {{Your_email}}
How to create API_TOKEN_GITHUB
secret
Generate your personal token following the steps:
- Go to the Github Settings (on the right-hand side of the profile picture)
- On the left-hand side pane click on "Developer Settings"
- Click on "Personal Access Tokens"
- Generate a new token, choose "Repo". Copy the token.
Then make the token available to the Github Action following the steps:
- Go to the Github page for the repository that you push from, click on "Settings"
- On the left-hand side pane click on "Secrets"
- Click on "Add a new secret" and name it "API_TOKEN_GITHUB"
Now your Github repository secret will be available as {{ secrets.API_TOKEN_GITHUB}}
in your workflow.
Docs for used actions and settings
- actions/checkout@v2
- actions/cache@v2
- actions/setup-node@v1
- cpina/github-action-push-to-another-repository@master
- Github Encrypted secrets
3. Commit to the master branch to verify it's working
All set, after committing the updated version of the workflow.yml
file and creating a change on the master
-branch (in this case) you should see an ongoing GH Action that will build your codebase and then push it to the destination repository, your original Github Pages repository.
You can follow your build steps in the detailed console logs when selecting your latest commit in the Actions</> overview
Top comments (2)
Nice. In this example you use the matrix, but I don't see you defined it. I wonder if this is a copy-paste error, or if the matrix has some default values.
Also, where is your site? Can we have a link?
Hi Gabor,
Thanks for the remark, it was indeed not added to the workflow.yml. I have updated the article with the suggested changes.
I've tried it in my workflow without the specified matrix containing the NodeJS version, and it also works. According to the documentation (docs.github.com/en/free-pro-team@l...), if you don't define a specific NodeJS version, GitHub uses the environment's default Node.js version.
So both ways will work, but it's better to define the strategy in the workflow document.
You can find my site at vanwildemeerschbrent.github.io