Learning syntax of GitHub Workflow: Name, On, Jobs, Runs-on, Steps, Uses, Run

Learning syntax of GitHub Workflow: Name, On, Jobs, Runs-on, Steps, Uses, Run

Here’s a detailed breakdown of the standard workflow syntax elements in GitHub Actions.

1. name

Specifies the name of the workflow. This name appears in the GitHub Actions interface under the repository's "Actions" tab.

Optional:

If omitted, GitHub will assign a default name based on the filename.

Example:

xxxxxxxxxx
1
1
name: Build and Test Workflow

2. on

Defines the events that trigger the workflow. These can be repository events like push, pull_request, scheduled intervals, or manual triggers.

Examples:

• Trigger on a push event to the main branch:

  xxxxxxxxxx
  4
  1
  on:
  2
  push:
  3
     branches:
  4
     - main
  

• Trigger on a pull request:

  xxxxxxxxxx
  4
  1
  on:
  2
  pull_request:
  3
     branches:
  4
     - main
  

• Trigger on a schedule (uses cron syntax):

  xxxxxxxxxx
  3
  1
  on:
  2
  schedule:
  3
     - cron: "0 0   " # Runs daily at midnight
  

• Manual trigger:

  xxxxxxxxxx
  2
  1
  on:
  2
  workflow_dispatch:
  

3. jobs

Specifies the individual jobs to run in the workflow. Each job is a collection of steps that execute in a specified environment.

Example:

xxxxxxxxxx
6
1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    steps:
5
     - name: Checkout code
6
        uses: actions/checkout@v3

4. runs-on

Specifies the virtual environment (runner) where the job will execute.

Options:

• ubuntu-latest: Ubuntu Linux

• windows-latest: Windows

• macos-latest: macOS

• Self-hosted runners for custom environments.

Example:

xxxxxxxxxx
3
1
jobs:
2
  build:
3
    runs-on: ubuntu-latest

5. steps

Defines the sequence of tasks (steps) within a job. Steps can run actions or custom shell commands.

Example:

xxxxxxxxxx
7
1
steps:
2
   - name: Checkout code
3
    uses: actions/checkout@v3
4
   - name: Install dependencies
5
    run: npm install
6
   - name: Run tests
7
    run: npm test

6. uses

Specifies a reusable action to execute within a step. Actions are prebuilt tasks defined by the GitHub community or your repository.

Structure:

owner/repository@version

Example:

xxxxxxxxxx
2
1
- name: Checkout code
2
  uses: actions/checkout@v3

7. run

Specifies a shell command or script to execute within a step.

Example:

xxxxxxxxxx
6
1
- name: Print a message
2
  run: echo "Hello, World!"
3
- name: Run a script
4
  run: |
5
    npm install
6
    npm test

Full Example Combining All Elements

xxxxxxxxxx
22
1
name: CI Workflow
2
on:
3
  push:
4
    branches:
5
     - main
6
  pull_request:
7
    branches:
8
     - main
9
jobs:
10
  build:
11
    runs-on: ubuntu-latest
12
    steps:
13
     - name: Checkout code
14
        uses: actions/checkout@v3
15
     - name: Set up Node.js
16
        uses: actions/setup-node@v3
17
        with:
18
          node-version: '16'
19
     - name: Install dependencies
20
        run: npm install
21
     - name: Run tests
22
        run: npm test

Summary

This workflow is triggered on pushes or pull requests to the main branch. It runs on an Ubuntu environment, checks out the code, sets up Node.js, installs dependencies, and runs tests.