In this post I am going to explain how to set up a basic workflow that uses an existing GitHub action. This workflow will deploy a static web site to GitHub Pages every time a change is made to the master branch.
For this we are going to use the Deploy to GitHub Pages Action.
Create our workflow
The workflows of the repository are stored in the .github/workflows/
folder.
Create in this folder a .yml file (e.g. deploy-to-gh-pages.yml
you can name it however you want) and paste this:
name: Build and Deploy
on: [push] # defaults to master
permissions:
contents: write
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout ποΈ
uses: actions/checkout@v3
- name: Install and Build π§
run: |
npm install
npm run-script build
- name: Deploy π
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: build # The folder the action should deploy.
The build step
- name: Install and Build π§
run: |
npm install
npm run-script build
In this section we put the script required to compile the code before deploying. If there is no need just remove this section.
Options
with:
branch: gh-pages
folder: dist
All those options are environment variables that will be used by the Deploy to GitHub Pages Action in order to work.
The BRANCH
option is the branch you wish to deploy the build files to. It is gh-pages
by default so that github automatically set up your github pages website.
You need to create the
gh-pages
branch prior to this. The Action will fail if the branch does not exist.
The folder
option is the folder in your repository that you want to deploy. It usually is dist
for Vue.js apps or build
for React.js apps.
the permissions
filed is required so that the script has sufficient rights to run.
Optionally if you want to use a specific access token you can add the token
option like this:
token: ${{ secrets.ACCESS_TOKEN }}
This option is the access token used to authorize the action to manipulate your repository.
You can generate this token in Profile Settings / Developer settings and add it in your repository's
secrets
inSettings/Secrets
Custom domain name
If you are using a custom domain name you will need to add beforehand a CNAME
file at the root of the gh_pages
branch with your domain name in it.
e.g.
dev.to
If you are not using a custom domain name, then do not forget to specify that your project is not hosted at the server root.
- For Vue.js apps add this in
vue.config.js
. Further information.
module.exports = {
publicPath: process.env.NODE_ENV === 'production'
? '/repository-name/'
: '/'
}
- For React.js apps add this your
package.json
. Further information.
"homepage":"https://yourusername.github.io/repository-name"
Specify the branch (Optional)
By default, this will use the master
branch when changes are made.
To change that replace the on: [push]
for this property with name of the branch of which you'd like this to run on.
on:
push:
branches:
- main
note: Your workflows won't appear in the
Actions
tab if they are not pushed on themaster
branch. However, you can still access your workflowβs runs in the commit's detail.
That's it! Push your changes and you can now watch the magic operate in the Actions tab.
And we can see that the app was deployed to GitHub Pages You can check out your deployments by clicking the environment
button in the Code tab:
You might have to disable/enable the github page option in the settings tab the first time the action run. You can do that by changing the Source setting to master
then back to gh-pages
.
The link to your live app is https://yourusername.github.io/repository-name
Top comments (12)
Nice write up!
I think
${{ secrets.ACCESS_TOKEN }}
in your example can be replaced with${{ secrets.GITHUB_TOKEN }}
, which is a repo-scoped token automatically generated for you by GitHub. Did you try this?Thanks!
I just tried it, but it didn't work.
Also, I couldn't find the documentation about this auto generated token.
Hmmm. Itβs documented here:
But maybe it doesnβt carry the right permissions for your use case. Did you get a permissions error?
When the Action try to push the changes, it pops this error in the logs:
fatal: could not read Password for 'https://***@github.com': No such device or address
That must be a permissions error. The personal access token that I generated before (
ACCESS_TOKEN
) had full control of my private repositories.could you upgrade this article to v3
Done !
Fixed it ! π
How do we implement the process.env with plain html/css/vanilla js?
Please explain -- why should I use it? GitHub Pages are already automatically deployed. What am I missing?
For project like React, Vue or Angular you will need to build the project to have the html,css and js files that Github Pages can serve.
Github Actions will automate this step for you.
You mean, for sites that are not simple Jekyll? Got it.
Thanks π