GitHub Actions Workflows

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.

Directory Structure

To get started with GitHub Actions, you need to create a directory to store your workflow files. Workflows are defined in YAML files and must be located in the .github/workflows directory in your repository.

• If the folder doesn’t exist, create it: .github/workflows

Managing Workflows with the GitHub CLI

The GitHub CLI (gh) provides a convenient way to manage your workflows from the terminal.

Manually Trigger a Workflow

You can manually run a workflow that is configured to be triggered by workflow_dispatch.

gh workflow run <workflow_file.yml> --ref <branch_name>

List Workflow Runs

To view the history of runs for a specific workflow:

gh run list --workflow <workflow_file.yml>

Workflow Syntax: Chaining Jobs

In a workflow, you can define multiple jobs that run independently or in sequence. To create a dependency where one job must wait for another to complete, you can use the needs keyword.

In the example below, the ttt job has a dependency on the deploy job. This means ttt will only start after the deploy job has successfully finished.

Example: Dependent Jobs

# Example workflow demonstrating a job dependency
name: Deploy Bind9
on:
  # Triggers the workflow on pushes to the 'uat' branch
  # that affect the specified paths.
  push:
    branches:
      - uat
    paths:
      - 'docker-workloads/bind9/**'
      - '.github/workflows/bind9.yml'
 
  # Allows manual triggering of the workflow from the GitHub UI or CLI
  workflow_dispatch:
 
permissions:
  contents: write
 
jobs:
  # First job
  deploy:
    name: test
    runs-on: [self-hosted]
    steps:
      - name: Set up SSH for remote access
        run: |
          echo "This is the first job."
 
  # Second job, which depends on the 'deploy' job
  ttt:
    # 'needs' creates the dependency. This job will not run
    # unless the 'deploy' job completes successfully.
    needs: deploy
    name: bind9 workflow
    # This job uses a reusable workflow from another repository.
    uses: example-org/homelab/.github/workflows/docker.yml@uat
    with:
      stack_name: bind9
      compose_source: docker-workloads/bind9
      docker_host: 10.0.0.50
      remote_user: deploy
      docker_network: backend
    secrets:
      ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}