ORIGIN

GitHub Actions Workflow

GitHubCI/CDGitHub Action Triggers Job Artifacts 5 mins835 words

GitHub Actions is a CI/CD and automation tool built into GitHub. Workflows allow you to automate tasks like testing, building, deploying, or managing your code lifecycle.

Workflow Structure Overview

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
name: <Workflow Name>         # Name shown in GitHub Actions UI

on:                           # Event trigger
  <event>: <conditions>

jobs:                         # One or more jobs to run
  <job-id>:
    name: <Job name>
    runs-on: ubuntu-latest    # GitHub-hosted runner environment
    steps:
      - name: <Step name>
        uses: <action>@<version>    # For reusable actions
        run: <shell command>        # For custom bash scripts
        env:
          MY_ENV_VAR: "value"

Trigger Types (on:)

1. push

Run workflow when code is pushed:

1
2
3
on:
  push:
    branches: [main, dev]

2. pull_request

Trigger on PR events like opened, closed, or synchronized:

1
2
3
on:
  pull_request:
    types: [opened, synchronize, closed]

3. workflow_dispatch

Enable manual runs from GitHub UI (with optional input parameters):

1
2
3
4
5
6
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Release version'
        required: true

  • inputs.version: Define a custom input for the workflow. You can access it via ${{ github.event.inputs.version }}

  • You can trigger this from API using a POST request to:

    1
    POST https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_ID/dispatches

    With body:

    1
    2
    3
    4
    5
    6
    {
      "ref": "main",
      "inputs": {
        "version": "v1.0.0"
      }
    }

4. schedule

Run on a fixed schedule (UTC cron syntax):

1
2
3
on:
  schedule:
    - cron: '0 0 * * 0'  # Every Sunday at midnight

Jobs and Steps

Jobs:

  • Each job runs independently unless defined in needs:
  • Run on a VM or Docker container
1
2
3
4
5
6
7
8
9
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Run tests
        run: npm test

Dependencies between jobs:

1
2
3
4
5
6
7
jobs:
  build:
    ...

  deploy:
    needs: build
    ...

Use

Every action you reference must be either a local action (./.github/actions/) or from GitHub Marketplace.

Syntax: uses: owner/repo@version

Tip: Always pin to a specific @version instead of @latest to avoid future breaking changes.

Common uses: Actions

Action Description
actions/checkout@v4 Checks out your code
actions/setup-node@v4 Setup Node.js runtime
docker/build-push-action@v5 Build and push Docker images
actions/upload-artifact@v4 Upload files (artifacts) between jobs
actions/download-artifact@v4 Download artifacts uploaded from another job

with: Supplies Inputs to Actions

Many actions take arguments via with::

1
2
3
- uses: actions/setup-node@v4
  with:
    node-version: '18'

You can do the same with your custom composite actions or when using marketplace actions.

Secrets and Variables

Secrets (for sensitive info):

  • Stored in GitHub repo → Settings → Secrets → Actions
  • Access via ${{ secrets.MY_SECRET }}

Variables (non-sensitive config):

  • Defined in Settings → Variables
  • Access via ${{ vars.MY_VARIABLE }}
1
2
3
env:
  SSH_KEY: ${{ secrets.DEPLOY_KEY }}
  DEPLOY_PATH: ${{ vars.PATH }}

Common Bash run: Usage

1
2
3
4
5
6
7
- name: Install dependencies
  run: |
    npm install
    npm run build

- name: Upload files
  run: scp -i key.pem file.tar.gz $USER@$HOST:$DEPLOY_PATH/

Multi-line commands use the pipe | symbol.

Workflow Dispatch Inputs (manual triggers)

1
2
3
4
5
6
7
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment environment'
        required: true
        default: 'staging'

Access it in run::

1
${{ github.event.inputs.environment }}

Use workflow_dispatch with the GitHub REST API:

1
2
3
4
5
curl -X POST \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  https://api.github.com/repos/OWNER/REPO/actions/workflows/WORKFLOW_FILE.yaml/dispatches \
  -d '{"ref":"main","inputs":{"environment":"prod"}}'

Matrix Builds (Test multiple envs)

1
2
3
4
5
6
7
8
9
10
11
jobs:
  test:
    strategy:
      matrix:
        node-version: [14, 16, 18]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm install && npm test

Artifacts (Share files between jobs)

In GitHub Actions workflows, each job runs in its own isolated environment (runner). This means files created or modified in one job are not automatically available in another job.

Artifacts are files or directories that you explicitly upload from one job and then download in another job within the same workflow run. GitHub stores these files temporarily in a central storage location called artifact storage.

name: Logical identifier for this artifact

path: File or folder path on the runner to upload

Upload:

1
2
3
4
- uses: actions/upload-artifact@v4
  with:
    name: build-zip
    path: ./dist/

Download:

1
2
3
4
- uses: actions/download-artifact@v4
  with:
    name: build-zip    # Must match the upload artifact name
    path: ./restore/   # Directory to restore files to

Files uploaded are stored in GitHub’s artifact storage and can be downloaded in later jobs, or even after the workflow finishes.

Tips

  • Each step: can use either uses: (for reusable actions) or run: (for custom shell commands), not both.

  • Use env: at job or step level to avoid repeating variables.

  • Use matrix builds for multiple versions or environments.

  • Use artifacts to share outputs

  • Avoid exposing secrets via echo

  • Prefer workflow_dispatch for production deploys

  • Use matrix: for multi-version testing

TOP
COMMENT
  • ABOUT
  • |
  • DONATE
o_oyao
  The Jigsaw puzzle is incomplete with even one missing piece. And I want to be the last piece to make the puzzle complete.
Like my post?
Default QR Code
made with ❤️ by o_oyao
©o_oyao 2019-2025

|