GitHub Pages allows you to publish static files, but it doesn't allow you to generate these. This is a problem if you want to generate ExDocs for a private package or generate a static website with a web framework like Angular.
The only way to have static files published on GitHub Pages is to put them on the repo, either in /docs
or in a branch named gh-pages
. Let's do this using GitHub Actions.
SSH key
Generating a new SSH key will allow you to push change to your Git repository from a GitHub Action. We'll use this to generate ExDocs and push them whenever there's a push on master
.
ssh-keygen -t ed25519 -C "gh-pages"
Deploy key
A deploy key is an SSH key that grants access to a single repository. GitHub attaches the public part of the key directly to your repository instead of a personal user account, and the private part of the key remains on your server.
Add the public key to the Deploy keys in /settings/keys
.
Action secrets
Secrets are environment variables that are encrypted. Anyone with
collaborator access to this repository can use these secrets for Actions.
Add the private key to the Repository secrets in /settings/secrets/actions
.
GitHub Action
With this setup, your GitHub Actions now have the ability to modify the repository. Depending on weather you want to put the docs in /docs
or in gh-pages
, the steps will be very similar.
Using a GitHub Action, we'll execute these steps:
- Generate ExDocs in
/doc
- Initialize a Git repository in
/doc
- Link this new local repo to your repository
- Force push the whole directory to
gh-pages
Here's an example of the GitHub Actions file.
name: GitHub Pages
on:
push:
branches: [master]
jobs:
build:
name: Push to gh-pages
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Elixir
uses: erlef/setup-beam@988e02bfe678367a02564f65ca2e37726dc0268f
with:
elixir-version: "1.13.3" # Define the elixir version [required]
otp-version: "24" # Define the OTP version [required]
- name: Restore dependencies cache
uses: actions/cache@v2
with:
path: deps
key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }}
restore-keys: ${{ runner.os }}-mix-
- name: Install dependencies
run: mix deps.get
- name: Force push to gh-pages
run: |
# Generate docs
mix docs
# Setup
cd doc
git init --initial-branch gh-pages
git remote add origin $ORIGIN
git config user.name "$NAME"
git config user.email "$EMAIL"
eval `ssh-agent -s`
ssh-add - <<< '${{ secrets.GH_PAGES_SSH }}'
# Push
git add .
git commit -m "mix docs"
git push --set-upstream origin gh-pages -f
In this file, you'll have to replace the variables $NAME
, $EMAIL
and $ORIGIN
.
Once it's commited to master
, the GitHub Pages will be automatically deployed!
Top comments (0)