Markup: md
Description: Example setup for using Github actions to build and deploy Pagegen site.

<div class="side-content">
<h2>Github Actions</h2>
<p>Github Actions are a continuous integration and continuous delivery (CI/CD) platform for running automated building, test, and deployment pipelines.</p>
</div>

Generating static pages is of course a major element of using static site generators. When working on a site, typically it is generated often, so it pays to streamline this step. When working locally regeneration can be automatic with `pagegen --serve <environment>` command, but for production a deployment pipeline is a common approach. The following will explain how the pipeline setup for this site which uses Github Actions.


## Overview pagegen.phnd.net pipeline

Once content is created and pushed to the [pagegen.phnd.net repository](https://github.com/oliverfields/pagegen_site), Github looks for any defined workflows and finds [.github/workflows/deploy_site.yml](https://github.com/oliverfields/pagegen_site/blob/master/.github/workflows/deploy_site.yml). The `deploy_site.yml` file is used by Github Actions to build the site, basically running the regular pagegen command. A deploy hook uploads the site to the web server, in this case using FTP.

<graphviz>dot pagegen_pipeline.svg
	digraph D {
		rankdir="LR"

		node [ shape="box" style="filled" fontsize=11 fillcolor="#EEEEEE" color="#CCCCCC" fontcolor="#3E4349" fontname="helvetica" ]

		content [ label=< Create<BR/>content > ]
		push [ label=< Push to<BR/>Github repository > ]
		action [ label=< Github Action<BR/>generates site > ]
		site [ label=<Site<BR/>deployed > ]

		content -> push
		push -> action
		action -> site
	}
</graphviz>


## deploy_site.yml highlights

The following describes key aspects of the workflow configuration. Github of course provides [full documentation](https://docs.github.com/en/actions).

First conditions for running the workflow are defined, in this case a push to the master branch will trigger the workflow.

	name: Deploy pagegen.phnd.net
	on:
	  workflow_dispatch:
	  push:
	    branches:
	      - master

Further the job steps are defined, the first few basically choose Ubuntu as OS, install Python and checkout the repository so it is available for generation and installs pagegen.

	jobs:
	  build_job:
	    name: Deploy site
	    runs-on: ubuntu-latest
	    steps:
	    - name: Install Python
	      uses: actions/setup-python@v2
	      with:
	        python-version: 3.8
	    - name: Checkout website source
	      id: checkout-master
	      uses: actions/checkout@v2
	    - name: Install Pagegen
	      run: |
	        pip install pagegen

The next step is to run the pagegen command on the checked out repository (the `Checkout website source` step above) and finally to upload the site to FTP server. The FTP upload is implemented as a [script](https://github.com/oliverfields/pagegen_site/blob/master/hooks/deploy) that gets run by Pagegen's deploy_hook.

	    - name: Generate site
	      id: run-pagegen
	      env:
	        ACTIONS_PAGEGEN_FTP_HOST: ${{ secrets.ACTIONS_PAGEGEN_FTP_HOST }}
	        ACTIONS_PAGEGEN_FTP_USERNAME: ${{ secrets.ACTIONS_PAGEGEN_FTP_USERNAME }}
	        ACTIONS_PAGEGEN_FTP_PASSWORD: ${{ secrets.ACTIONS_PAGEGEN_FTP_PASSWORD }}
	        ACTIONS_PAGEGEN_FTP_TARGET_DIRECTORY: ${{ secrets.ACTIONS_PAGEGEN_FTP_TARGET_DIRECTORY }}
	      run: |
	        cd /home/runner/work/pagegen_site/pagegen_site
	        pagegen -g "prod"


Because security the deploy script is made to look for sensitive information in the Actions environment. These [encrypted secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) become environment variables available during the workflow. They are managed from the Github site.

To summarize a simple `git push` command will update the web site.