Actions¶

GitHub Actions are predefined applications from the GitHub Marketplace that allow you to automate repeated tasks. Specifically, they allow you to automatically trigger "workflows" on certain "events" (see below sections). This workflows could be running your defined tests on your code, automatically building documentation using MkDocs to a GitHub.io Page, or continuous deployment of your projects with Docker. The events that trigger these workflows can be the creation of an issue or a pull request, pushing to the main branch, etc. An action can clone your repository from GitHub, set up a Python environment, set up authentication to a remote directory, and then run these workflows on certain events.

Workflows¶

A workflow is a configurable automated process that will process one or more jobs. They are defined by a YAML file in your repository that is run when triggered by an event that occurs in your repository. They are stored in the .github/workflows directory within your repository, this directory can contain multiple YAML files that each have their own triggering conditions and tasks.

Events¶

An event is just a specific activity that happens within your repository that can be used to trigger a workflow. The trigger can originate from GitHub, or it can be scheduled to run at a specific time. The triggers from GitHub, as mentioned earlier, can include pushing to a branch, making a pull request, but there are many more which are listed on a webpage, see here.

Jobs¶

A job is a set of steps that are executed in a workflow, this could be a script or action that is run. Steps are run sequentially and are dependant on each other, they are also able to share data between them. So for example, you could have a job in which the first step is to build an application, followed by a step that runs tests on the application that was built.

Jobs can also be configured to be dependant on other jobs, but be default they are independant and run in parallel. When one job is dependant on another it will wait for the dependant job to be completed before it can be run. For example, you could have multiple build jobs for different OSs that are independant, but a packaging job that is dependant on those jobs. In this case, the build jobs would run in parallel, however, the packaging job would only be run once all of those have completed.

Creating a Workflow¶

Now we are going to create a workflow in your practice repository. The workflow isn't going to do anything special, it will simply print the version of Python that is installed in the workflow and it will be triggered by a git push.

In your repository create the .github/workflows/ directory.
In the .github/workflows/ directory, create a new file called test.yml and copy in the example workflow code below.
Example workflow
```
name: 'Test Workflow - Print Python Version'
on: push
jobs:
  test-workflow:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-python@v3
      - run: python --version
```
1. Commit and push the changes to your repository.
2. Make a small change, commit and push it to activate the workflow.

Viewing Workflow Activity¶

When a workflow is triggered, GitHub displays a visualisation of its progress and outputs the workflows log.

On GitHub, navigate to the repository's main page.
Under the repository's name click Actions.
Click the workflow run that you want to see.
Click on the job that you want to see.
Revel in the glory of your job's successful execution.

Example Workflow YAML File

name: Documentation Build
on:
  push:
    branches:
      - main
      - restructure
jobs:
  mkdocs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: 3.7
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force