DEV Community

Brent Vanwildemeersch
Brent Vanwildemeersch

Posted on • Updated on

Deploy to Github Pages using Github Actions

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}}
Enter fullscreen mode Exit fullscreen mode

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

  1. actions/checkout@v2
  2. actions/cache@v2
  3. actions/setup-node@v1
  4. cpina/github-action-push-to-another-repository@master
  5. 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)

Collapse
 
szabgab profile image
Gabor Szabo

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?

Collapse
 
vanwildemeerschbrent profile image
Brent Vanwildemeersch

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