From 9f367ae7e7af33b58be8335899708ab2d80f5213 Mon Sep 17 00:00:00 2001 From: Maximilian Schoenenberg Date: Mon, 14 Sep 2020 10:36:56 +0200 Subject: [PATCH] Added description for github actions (#1163) * Added description for github actions * Added specific version and removed outdated sentence regarding branch naming --- .../documentation/deployment/github-pages.md | 51 ++++++++++++++++--- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/docs/content/documentation/deployment/github-pages.md b/docs/content/documentation/deployment/github-pages.md index 5ba0287d..437f9d30 100644 --- a/docs/content/documentation/deployment/github-pages.md +++ b/docs/content/documentation/deployment/github-pages.md @@ -6,17 +6,56 @@ weight = 30 By default, GitHub Pages uses Jekyll (a ruby based static site generator), but you can also publish any generated files provided you have an `index.html` file in the root of a branch called `gh-pages` or `master`. In addition you can publish from a `docs` directory in your repository. That branch name can -also be manually changed in the settings of a repository. **However**, this only applies to publishing in a custom domain, -i.e., if you want to publish to a GitHub-provided web service under the `github.io` domain, you can **only** use the -`master` branch of your repository, as explained -[here](https://help.github.com/en/articles/configuring-a-publishing-source-for-github-pages), -so we will focus on the method that will work regardless of the domain. +also be manually changed in the settings of a repository. We can use any continuous integration (CI) server to build and deploy our site. For example: - * [Github Actions](https://github.com/shalzz/zola-deploy-action) + * [Github Actions](#github-actions) * [Travis CI](#travis-ci) +## Github Actions + +Using *Github Actions* for the deployment of your Zola-Page on Github-Pages is pretty easy. You basically need three things: + +1. A *Personal access token* to give the *Github Action* the permission to push into your repository. +2. Create the *Github Action*. +3. Check the *Github Pages* section in repository settings. + +Let's start with the token. + +For creating the token either click on [here](https://github.com/settings/tokens) or go to Settings > Developer Settings > Personal access tokens. Under the *Select Scopes* section, give it *repo* permissions and click *Generate token*. Then copy the token, navigate to your repository and add in the Settings tab the *Secret* `TOKEN` and paste your token in it. + +Next we need to create the *Github Action*. Here we can make use of the [zola-deploy-action](https://github.com/shalzz/zola-deploy-action). Go to the *Actions* tab of your repository, click on *set up a workflow yourself* to get a blank workflow file. Copy the following script into it and commit it afterwards. + +```yaml +# On every push this script is executed +on: push +name: Build and deploy GH Pages +jobs: + build: + name: shalzz/zola-deploy-action + runs-on: ubuntu-latest + steps: + # Checkout + - uses: actions/checkout@master + # Build & deploy + - name: shalzz/zola-deploy-action + uses: shalzz/zola-deploy-action@v0.12.0 + env: + # Target branch + PAGES_BRANCH: gh-pages + # Provide personal access token + TOKEN: ${{ secrets.TOKEN }} +``` + +This script is pretty simple, because the [zola-deploy-action](https://github.com/shalzz/zola-deploy-action) is doing everything for you. You just need to provide some details. For more configuration options check out the [README](https://github.com/shalzz/zola-deploy-action/blob/master/README.md). + +By commiting the action your first build is triggered. Wait until it's finished, then you should see in your repository a new branch *gh-pages* with the compiled *Zola* page in it. + +Finally we need to check the *Github Pages* section of the repository settings. Click on the *Settings* tab and scroll down to the *Github Pages* section. Check if the source is set to *gh-pages* branch and the directory is */ (root)*. You should also see your *Github Pages* link. + +There you can also configure a *custom domain* and *Enforce HTTPS* mode. Before configuring a *custom domains*, please check out [this](https://github.com/shalzz/zola-deploy-action/blob/master/README.md#custom-domain). + ## Travis CI We are going to use [Travis CI](https://travis-ci.org) to automatically publish the site. If you are not using Travis