Describing standard workflow syntax elements in Github

Describing standard workflow syntax elements in Github

GitHub Workflows are defined using YAML syntax and have a specific structure to automate tasks. Below are the standard syntax elements and their roles.

1. name

Defines the name of the workflow. This is optional but helps identify workflows in the GitHub Actions interface.

xxxxxxxxxx
1
1
name: CI Workflow

2. on

Specifies the events that trigger the workflow. Events can be repository activities, manual triggers, or scheduled runs.

Examples:

• Trigger on a push event:

  xxxxxxxxxx
  1
  1
  on: push
  

• Trigger on a pull_request event:

  xxxxxxxxxx
  1
  1
  on: pull_request
  

• Multiple events:

  xxxxxxxxxx
  7
  1
  on:
  2
  push:
  3
     branches:
  4
     - main
  5
  pull_request:
  6
     branches:
  7
     - main
  

• Scheduled triggers (cron syntax):

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

• Manual triggers:

  xxxxxxxxxx
  2
  1
  on:
  2
  workflow_dispatch:
  

3. jobs

Defines one or more jobs that the workflow will execute. Jobs can run in parallel or sequentially based on dependencies.

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

Key Elements:

• runs-on: Specifies the environment for the job (e.g., ubuntu-latest, windows-latest, macos-latest).

• needs: Defines dependencies between jobs.

xxxxxxxxxx
6
1
jobs:
2
  test:
3
    runs-on: ubuntu-latest
4
  build:
5
    runs-on: ubuntu-latest
6
    needs: test

4. steps

Lists individual tasks within a job. Steps can use actions or custom shell commands.

xxxxxxxxxx
5
1
steps:
2
   - name: Checkout code
3
    uses: actions/checkout@v3
4
   - name: Run a shell command
5
    run: echo "Hello, World!"

Key Elements:

• name: A descriptive name for the step.

• uses: Specifies a prebuilt action to use.

• run: Runs a shell command or script.

• with: Provides input parameters for actions.

xxxxxxxxxx
4
1
- name: Set up Node.js
2
  uses: actions/setup-node@v3
3
  with:
4
    node-version: '16'

5. env

Sets environment variables for workflows, jobs, or steps.

Workflow-level:

xxxxxxxxxx
2
1
env:
2
  NODE_ENV: production

Job-level:

xxxxxxxxxx
5
1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    env:
5
      NODE_ENV: production

Step-level:

xxxxxxxxxx
5
1
steps:
2
   - name: Print environment variable
3
    run: echo $NODE_ENV
4
    env:
5
      NODE_ENV: production

6. outputs

Defines output values from jobs that can be used in other jobs.

xxxxxxxxxx
13
1
jobs:
2
  job1:
3
    runs-on: ubuntu-latest
4
    outputs:
5
      example_output: ${{ steps.example_step.outputs.result }}
6
    steps:
7
     - id: example_step
8
        run: echo "::set-output name=result::value"
9
  job2:
10
    runs-on: ubuntu-latest
11
    needs: job1
12
    steps:
13
     - run: echo "Output from job1 is ${{ needs.job1.outputs.example_output }}"

7. defaults

Sets default values for run steps.

xxxxxxxxxx
4
1
defaults:
2
  run:
3
    shell: bash
4
    working-directory: scripts

8. permissions

Specifies permissions for the workflow's access to the GitHub API.

xxxxxxxxxx
2
1
permissions:
2
  contents: read

9. secrets

Accesses sensitive information stored in the repository.

xxxxxxxxxx
5
1
steps:
2
   - name: Use secret
3
    run: echo $MY_SECRET
4
    env:
5
      MY_SECRET: ${{ secrets.MY_SECRET }}

10. if

Adds conditional execution for jobs or steps.

xxxxxxxxxx
4
1
steps:
2
   - name: Run only on main branch
3
    if: github.ref == 'refs/heads/main'
4
    run: echo "On main branch"

11. strategy

Defines a matrix of configurations to test multiple environments or inputs.

xxxxxxxxxx
11
1
jobs:
2
  test:
3
    runs-on: ubuntu-latest
4
    strategy:
5
      matrix:
6
        node-version: [12, 14, 16]
7
    steps:
8
     - name: Set up Node.js
9
        uses: actions/setup-node@v3
10
        with:
11
          node-version: ${{ matrix.node-version }}

12. timeout-minutes

Sets a timeout for a job.

xxxxxxxxxx
4
1
jobs:
2
  build:
3
    runs-on: ubuntu-latest
4
    timeout-minutes: 10

Summary

These elements work together to create flexible and powerful workflows. You can customize them to fit the needs of your automation.