# GitHub Pages Deploy Action :rocket:
[](https://github.com/JamesIves/github-pages-deploy-action/actions) [](https://github.com/JamesIves/github-pages-deploy-action/actions) [](https://github.com/marketplace/actions/deploy-to-github-pages) [](https://github.com/JamesIves/github-pages-deploy-action/releases)
This [GitHub action](https://github.com/features/actions) will handle the deploy process of your project to [GitHub Pages](https://pages.github.com/). It can be configured to upload your production-ready code into any branch you'd like, including `gh-pages` and `docs`.
## Getting Started :airplane:
You can include the action in your workflow to trigger on any event that [GitHub actions supports](https://help.github.com/en/articles/events-that-trigger-workflows). If the remote branch that you wish to deploy to doesn't already exist the action will create it for you. Your workflow will also need to include the `actions/checkout` step before this workflow runs in order for the deployment to work.
You can view an example of this below.
```yml
name: Build and Deploy
on: [push]
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2 # If you're using actions/checkout@v2 you must set persist-credentials to false in most cases for the deployment to work correctly.
with:
persist-credentials: false
- name: Build and Deploy
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages # The branch the action should deploy to.
FOLDER: build # The folder the action should deploy.
```
If you'd like to make it so the workflow only triggers on push events to specific branches then you can modify the `on` section.
```yml
on:
push:
branches:
- master
```
---
### Using an SSH Deploy Key 🔑
If you'd prefer to use an SSH deploy key you must first generate a new SSH key by running the following terminal command, replacing the email with one connected to your GitHub account.
```
ssh-keygen -t rsa -b 4096 -C "youremailhere@example.com" -N ""
```
Once you've generated the key pair you must add the contents of the public key within your repositories [deploy keys menu](https://developer.github.com/v3/guides/managing-deploy-keys/). You can find this option by going to `Settings > Deploy Keys`, you can name the public key whatever you want. Afterwards add the contents of the private key to the `Settings > Secrets` menu as `DEPLOY_KEY`.
With this configured you must add the `ssh-agent` step to your workflow and set `SSH` to `true` within the deploy action.
```yml
- name: Install SSH Client
uses: webfactory/ssh-agent@v0.2.0
with:
ssh-private-key: ${{ secrets.DEPLOY_KEY }}
- name: Build and Deploy
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
SSH: true
BRANCH: gh-pages
FOLDER: 'site'
```
You can view a full example of this here.
```yml
name: Build and Deploy
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
with:
persist-credentials: false
- name: Install
run: |
npm install
npm run-script build
- name: Install SSH Client
- uses: webfactory/ssh-agent@v0.2.0 # This step installs the ssh client into the workflow run. There's many options available for this on the action marketplace.
with:
ssh-private-key: ${{ secrets.DEPLOY_KEY }}
- name: Build and Deploy Repo
uses: JamesIves/github-pages-deploy-action@releases/v3-test
with:
BASE_BRANCH: master
BRANCH: gh-pages
FOLDER: 'build'
CLEAN: true
SSH: true # SSH must be set to true so the deploy action knows which protocol to deploy with.
```
You can view an example of this pattern here.
```yml
name: Build and Deploy
on: [push]
jobs:
build:
runs-on: windows-latest # The first job utilizes windows-latest
steps:
- name: Checkout
uses: actions/checkout@v2
with:
persist-credentials: false
- name: Install # The project is built using npm and placed in the 'build' folder.
run: |
npm install
npm run-script build
- name: Upload Artifacts # The project is then uploaded as an artifact named 'site'.
uses: actions/upload-artifact@v1
with:
name: site
path: build
deploy:
needs: [build] # The second job must depend on the first one to complete before running, and uses ubuntu-latest instead of windows.
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v2
with:
persist-credentials: false
- name: Download Artifacts # The built project is downloaded into the 'site' folder.
uses: actions/download-artifact@v1
with:
name: site
- name: Build and Deploy
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages
FOLDER: 'site' # The deployment folder should match the name of the artifact. Even though our project builds into the 'build' folder the artifact name of 'site' must be placed here.
```