Setting Up Workflow Files

1. Creating Workflow File

GitHub Actions workflows are defined using YAML files stored in the .github/workflows directory of your repository.

File Location	Format	Description
`.github/workflows/<workflow-name>.yml`	`YAML`	Directory and file name for the workflow configuration

Example: Basic workflow file structure

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello, world!"

2. Naming Workflows

Workflow Name	Description	Requirements
name	Name of the workflow	Required field in workflow file

Example: Setting Workflow Name

name: Deploy to Production

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

Note: Workflow names are case-sensitive and can include spaces, underscores, hyphens, and periods.

3. Defining Workflow Syntax

Field	Description	Required	Example
name	Workflow name	No	`Deploy to Production`
on	Triggers for the workflow	Yes	`push`, `pull_request`
jobs	Workflow jobs to run	Yes	`build`, `test`

Example: Basic Workflow Syntax

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello, world!"

4. Using Workflow Templates

Example: Using a GitHub-provided workflow template

name: Node.js CI
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test

Template Source	Description	Usage
GitHub Actions	Official templates provided by GitHub	Available in the repository's `.github/workflows` directory or via the GitHub UI
Community Templates	Templates created by the community	Found on GitHub or in third-party repositories

How to Use Templates

Navigate to .github/workflows in your repository
Click on "Create new file"
Select a template from the GitHub Actions templates or paste your own
Customize the workflow as needed

5. Organizing Multiple Workflows

Workflow Organization Strategy

Create a .github/workflows directory in your repository root
Place each workflow file with a descriptive name (e.g., deploy-production.yml)
Use consistent naming conventions to distinguish workflow types
Group related workflows under subdirectories if needed (e.g., .github/workflows/deploy/)

Workflow File	Description	Trigger	Usage
`build.yml`	Builds project artifacts	Push to `main`	Continuous integration
`deploy-staging.yml`	Deploys to staging environment	Push to `develop`	Pre-production testing
`deploy-production.yml`	Deploys to production environment	Push to `release`	Production deployment

Example: Workflow File Organization

# .github/workflows/deploy-production.yml
name: Deploy to Production
on:
  push:
    branches:
      - release
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Deploy to production
        run: echo "Deploying to production..."

Note: GitHub Actions supports up to 100 workflow files per repository. Consider organizing workflows by function or environment.

6. Validating Workflow Syntax

Example: Basic workflow syntax validation

name: Validate Workflow
on:
  push:
    branches: [ main ]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Validate workflow syntax
        run: |
          echo "Workflow file is syntactically valid"

Validation Method	Description	Notes
GitHub Actions Validator	Uses GitHub's built-in validation for workflow files	Available in the Actions tab of your repository
Local CLI Validation	Use `act` or `github-action-validator`	Requires local setup and installation
YAML Linting	Validate YAML syntax with tools like `yamllint`	Ensures valid YAML structure before GitHub processing

Note: GitHub Actions workflows must be valid YAML and follow strict formatting rules. Any syntax errors will prevent workflow execution.

Warning: Workflows with invalid syntax will show an error in the GitHub UI and will not run.

7. Setting Workflow Defaults

Property	Values	Description
defaults.run	`{ shell: string, working-directory: string }`	Sets default shell and working directory for all `run` steps in the workflow.

Example: Setting Default Shell and Working Directory

defaults:
  run:
    shell: bash
    working-directory: src

Note: The defaults.run configuration applies to all run steps in the workflow unless overridden in an individual step.

8. Disabling Workflows

Option	Description	Notes
on: workflow_dispatch: enabled: false	Disables manual triggering of the workflow	Useful for workflows that should only run on schedule or event
if: false	Conditionally disables workflow execution	Can be used to disable workflows based on environment or other conditions

Example: Disabling Workflow via Configuration

name: Example Workflow
on:
  workflow_dispatch:
    enabled: false
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "This workflow is disabled"

Note: Disabling workflows via enabled: false does not remove them from the repository and they can still be triggered manually if permissions allow it.

9. Versioning Workflows

Version	Description	Notes
v1	Initial stable version of GitHub Actions	Legacy, not recommended for new workflows
v2	Improved performance and reliability	Recommended for most use cases
v3	Latest stable version with new features	Includes support for newer runners and tools

Example: Using v3 in workflow file

name: Example Workflow
on:
  push:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

Note: Always pin your workflow to a specific version to ensure stability and prevent unexpected behavior from updates.

10. Inheriting Workflow Settings

Setting	Description	Example
uses	Specifies a reusable workflow to inherit settings from	`uses: octocat/my-workflow@v1`
with	Passes parameters to the inherited workflow	`with: environment: production`
secrets	Passes secrets to the inherited workflow	`secrets: inherit`
variables	Passes environment variables to the inherited workflow	`env: inherit`

Example: Reusing a Workflow

name: Reusable Workflow
on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
    secrets:
      token:
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to environment
        run: echo "Deploying to ${{ inputs.environment }}"

Example: Inheriting from Reusable Workflow

name: Main Workflow
on:
  push:
    branches: [ main ]

jobs:
  inherit-deploy:
    uses: octocat/my-workflow@v1
    with:
      environment: production
    secrets:
      token: ${{ secrets.GITHUB_TOKEN }}