CI/CD Basics

Github Actions

Github actions is a remote CI/CD system that is integrated with github directly

Github Actions Files are YML/YAML

Github actions files are written in YAML/YML

For example this presentation has a pipeline

name: GH build for ezprez

on:
  push:
    branches:
      - master
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repo
      uses: actions/checkout@v2
    - name: Setup Python
      uses: actions/setup-python@v2
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        python -m pip install --upgrade setuptools wheel
        python -m pip install ezprez
    - name: build html files
      run: |
        mkdir ~/Downloads
        python example.py
        mv Presentation/* .
        rm -rf Presentation
    - name: Deploy Docs
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: .

Github Actions File structure

They go in a folder in your repository called /.github/workflows (you can have multiple pipelines)

Triggers

This configuration determines when an action pipeline runs. Note that multiple pipelines can be run off a single trigger, and pipelines finishing can trigger other pipelines to start. After a name parameter you need to add an 'on'

name: GH build for ezprez

on:
  ... # This is where you add your trigger

On push (all branches)

name: GH build for ezprez

on:
  [push] # all branches

On push (specific branches)

name: GH build for ezprez

on:
  push:
    branches: # Only rub on a push to master or main
      - master
      - main

On Workflow dispatch (No Inputs)

name: GH build for ezprez

on:
  workflow_dispatch # Manually start the pipeline

On Workflow dispatch (Inputs)

name: GH build for ezprez

on:
  workflow_dispatch: # Manually start the pipeline
    inputs:
        doc_system: # Can access value ${{ github.event.inputs.doc_system }}
          description: Either pdoc, or mkdocs # Description shows under field
          default: pdoc # Provide a default
          required: true # Make field required or not

On Workflow dispatch (Inputs)

On Schedule/Cron

name: GH build for ezprez

on:
  schedule:
    # Run at 5:05 pm on mondays and wednesdays
    - cron: '5 17 * * 1,3'

Jobs

Each job is essentially a set of steps with some associated state. Each job runs in it's own 'runner' with it's own 'virtual environment'(container)

name: name of workflow

on:
  ... # This is where you add your trigger

jobs:
  job_name:
    name: You can also specify a name here
    ... # environment definition

Environment definitions

The information used to configure all steps in a job

runs-on

This defines what OS the workflow runs on

name: name of workflow

on:
  ... # This is where you add your trigger

jobs:
  job_name:
    name: You can also specify a name here
    runs-on: ubuntu-latest # can also be a matrix you iterate over

Strategy

Used to create arrays that are itterated over to run a job multiple times

name: name of workflow

on:
  ... # This is where you add your trigger

jobs:
  job_name:
    name: You can also specify a name here
    runs-on: ${{ matrix.os }} # Would run this with ubuntu-latest first, then windows-latest, then macos-latest
    strategy:
      matrix:
        python_version: ['3.7', '3.8', '3.9', '3.10'] # Can use this later on
        os: [ubuntu-latest, windows-latest, macOS-latest]

Steps

This is where actual commands are run. Note that state is typically persistant across steps in the same job. Note you can use other people's actions by passing the repo name

name: name of workflow

on:
  ... # This is where you add your trigger

jobs:
  job_name:
    ... # your job config

    steps:
    - uses: actions/checkout@v2 # minimal example
    - name: Set up Python ${{ matrix.python_version }} # Using a more complex pre-built example
      uses: actions/setup-python@v1 # https://github.com/actions/setup-python
      with:
        python-version: ${{ matrix.python_version }}
    - name: Install dependencies # Example of running raw bash commands
      run: |
        pip install .
        pip install pytest

Using with

With can be used to define settings for each step in a job. There are some standard one's we will cover but keep in mind custom actions often have custom settings you can use alongside the with section. It is essentially where you can stick any configuration for a step you need

Secrets

In github you can set a secret, which is a key-value pair that is kept completely secret (like a password). Be aware once set you can only modify or delete, you cannot read the value again

With options: token

Tokens are used to authenticate an action and are what allows the action access to make changes or even just access content that is locked behind a password/github account. They use different formats, but here is an example

name: Publish Site
on:
  ...
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Publish Site
        uses: chabad360/hugo-gh-pages@master
        with:
          githubToken: ${{ secrets.PERSONAL_TOKEN }} # In this case this is where you set a personal access token to your account

With options: artifacts

name: Create theme release # Taken from https://github.com/QU-UP/ezcv-themes/blob/main/.github/workflows/release.yml
on:
  workflow_dispatch:
    inputs:
      version_number:
        description: The version number to release
        default: "0.1.0"
        required: true
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repo
      uses: actions/checkout@v2

    - name: Create zip files
      ... # creates a bunch of zip files
    - name: Create release draft
      uses: ncipollo/release-action@v1
      with:
        artifacts: "*.zip" # Include zip files in releases draft
        tag: ${{ github.event.inputs.version_number }}
        draft: true
        token: ${{ secrets.GITHUB_TOKEN }}

What does this look like?

What does this look like?

What does this look like?