Note_Tech

All technological notes.

Project maintained by simonangel-fong Hosted on GitHub Pages — Theme by mattgraham

GitHub Actions: Fundamental

Back

Components

name: 01 - Building Block

on: push

jobs:
  echo-hello:
    runs-on: ubuntu-latest
    steps:
      - name: say hello
        run: |
          echo "hello world"
  echo-bye:
    runs-on: ubuntu-latest
    steps:
      - name: fails
        run: |
          echo "will fail"
          exit 1
      - name: say bye
        run: echo "Bye"

Events

name: 02 - workflow event

on:
  push:
  pull_request:
  schedule:
    - cron: "*/5 * * * *"
  workflow_dispatch:

jobs:
  echo:
    runs-on: ubuntu-latest
    steps:
      - name: Show trigger
        run: echo "triggerred by $" # triggerred by push

triggerred by push triggerred by workflow_dispatch triggerred by pull_request

Event Filters

on:
  push:
  branches:
    - main
    - "releases/**"
  paths-ignore:
    - "docs/**"

Activity Types

on:
  pull_request:
    types: [opened, synchronize]
    branches:
      - main
      - 'releases/**

Runners

name: 03 - runner
on: push

jobs:
  echo-ubuntu:
    runs-on: ubuntu-latest
    steps:
      - name: show os
        run: |
          echo Runner: $
  echo-windows:
    runs-on: windows-latest
    steps:
      - name: show os
        # required in win
        shell: bash
        run: |
          echo Runner: $

Runner: Linux Runner: Windows

Actions

- uses: {owner}/{repo}@{ref}
  with:
    param: value

GitHub Marketplace

Contexts

Context Description
github metadata about the workflow run, the repository, and the specific event that triggered the run.
env variables that have been defined in a workflow, job, or step.
secrets sensitive data like API keys or tokens, which are automatically masked in the logs.
vars variables defined at the organization, repository, or environment level.
job / jobs the current job info; jobs (for reusable workflows) provides outputs from other jobs in that workflow.
steps information and outputs from steps that have already completed in the current job.
runner Includes details about the machine executing the job, such as the operating system (runner.os).
matrix / strategy Used in matrix builds to access properties of the current iteration
needs dependencies for the current job.
inputs input properties passed via the keyword with to an action, to a reusable workflow, or to a manually triggered workflow.
    
name: 06 - Context
run-name: my run name $ | DEBUG - $

on:
  push:
  workflow_dispatch:
    inputs:
      debug:
        type: boolean
        default: false

env:
  MY_WORKFLOW_ENV: "workflow"
  MY_OVERWRITTEN_ENV: "workflow"

jobs:
  echo-context:
    runs-on: ubuntu-latest
    env:
      MY_JOB_ENV: "job"
      MY_OVERWRITTEN_ENV: "job"
    steps:
      - name: Display github info
        run: |
          echo "Event Name: $"
          echo "ref: $"
          echo "SHA: $"
          echo "Actor: $"
          echo "Workflow: $"
          echo "Run ID: $"
          echo "Run number: $"

      - name: Display variable
        run: |
          echo "Variable value: $"

      - name: Print env
        env:
          MY_OVERWRITTEN_ENV: "step"
        run: |
          echo "my workflow env: $"
          echo "my job env: $"
          echo "my overwritten env: $"

      - name: Print env
        run: |
          echo "my workflow env: $"
          echo "my job env: $"
          echo "my overwritten env: $"

  echo-context-2:
    runs-on: ubuntu-latest
    steps:
      - name: Print workflow env
        run: |
          echo "workflow: $MY_WORKFLOW_ENV"
          echo "Overwritten: $MY_OVERWRITTEN_ENV"

Expressions & Variables

Functions

name: 09 - function

on:
  pull_request:
  workflow_dispatch:

jobs:
  echo1:
    runs-on: ubuntu-latest
    steps:
      - name: Print PR title
        run: echo $

      - name: print PR labels
        run: |
          cat <<EOF
              $
          EOF

      - name: Bug step
        if: $
        run: echo "bug fixed"

      - name: Sleep for 20 seconds
        run: sleep 20

      - name: Failing step
        run: exit 1

      - name: step when success
        if: $
        run: echo "Execute only when success"

      - name: step when failure
        if: $
        run: echo "Execute only when failure"

      - name: step when cancel
        if: $
        run: echo "Execute only when cancelled"

      - name: step when not cancel
        if: $
        run: echo "Execute only when not cancelled"

Inputs

inputs:
  url:
    description: "..."
    required: true
  max-trials:
    description: "..."
    required: false
    default: "60"

jobs:
  job1:
    steps:
      - name: Ping URL
        uses: ping-url-example@v1
        with:
          url: https:./www.google.com
          max-trials: 10

Lab: Control Build-deploy flow by inputs

name: 11 - Inputs

on:
  workflow_dispatch:
    inputs:
      dry-run:
        type: boolean
        description: Skip deployment and only print build output
        default: false
      target:
        type: environment
        required: true
        description: Specify the target environment
      tag:
        type: choice
        options:
          - v1
          - v2
          - v3
        default: v3
        description: The release to build
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Build
        run: echo "Building from tag $"

  deploy:
    runs-on: ubuntu-latest
    if: $
    needs: build
    environment: $
    steps:
      - name: Deploy
        run: echo "Deploy to $"

Outputs

  1. Set step id
  2. pass key-value pair to $GITHUB_OUTPUT variable
  3. Specify key and value in the outputs key
  4. refer to outputs by needs.<job-id>.outputs.<key-name>
jobs:
  welcome:
    runs-on: ubuntu-latest
    outputs:
      name: $
    steps:
      - id: step1
        run: echo "NAME=Lauro" >> "$GITHUB_OUTPUT"
  goodbye:
    runs-on: ubuntu-latest
    needs: welcome
    steps:
      - run: echo "Bye, $"

Lab: output

name: 12 - Outputs

on:
  workflow_dispatch:
    inputs:
      build-status:
        type: choice
        options:
          - success
          - failure
        default: success

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      build-status: $
      key2: $
    steps:
      - name: Print GITHUB_OUTPUT path
        run: echo "$GITHUB_OUTPUT"

      - name: Build
        id: build
        run: |
          echo "$GITHUB_OUTPUT"
          echo "status=$" >> "$GITHUB_OUTPUT"

      - name: Pass multiple k-v github_output, and Accidentally remove
        id: key2
        run: |
          echo "key1=val1" >> "$GITHUB_OUTPUT"
          echo "key2=val2" >> "$GITHUB_OUTPUT"
          cat "$GITHUB_OUTPUT"

          echo "key3=val3" > "$GITHUB_OUTPUT"
          cat "$GITHUB_OUTPUT"

  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: $
    steps:
      - name: Deploy
        run: echo "Deploying"
      - name: Print kv2
        run: echo "$
        # unexpected EOF while looking for matching `"'Error: Process completed with exit code 2.
  1. GITHUB_OUTPUT path: /home/runner/work/_temp/_runner_file_commands/set_output_uuid they are the files different across steps, that is why it needs to specify the step id in the outputs key
  2. “key3=val3” > “$GITHUB_OUTPUT”: remove the kv2, leading to error in deploy job
  3. Deploy job executed: build-status can be fethed, because GITHUB_OUTPUT are independent per step.

Environment

Concurrency

Common Examples

concurrency:
  group: $-$
  cancel-in-progress: true

cancels older test runs if you push several commits to the same PR in quick succession.

concurrency:
  group: production-deploy
  cancel-in-progress: false

ensures only one deployment happens at a time without interrupting a run that is already mid-deploy.

Lab: Concurrency

name: 19 concurrency - jobs

on:
  workflow_dispatch:

jobs:
  ping-url-concurrency:
    runs-on: ubuntu-latest
    concurrency:
      group: $-$
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Ping URL
        id: ping-url
        uses: ./.github/actions/docker-ping-url
        with:
          url: "https://www.invalid.url"
          max_trials: 20
          delay: 5

  ping-url-without-concurrency:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Ping URL
        id: ping-url
        uses: ./.github/actions/docker-ping-url
        with:
          url: "https://www.invalid.url"
          max_trials: 20
          delay: 5

pic

Job level concurrency without concurrency control, incoming workflow is executed without waiting with concurrency control, incoming workflow is suspended and waiting.