Github Actions Detailed Syntax

Workflow File Structure

• name: A custom name for your workflow. Displayed in the GitHub UI.
• on: Defines the event that triggers the workflow. Can be a single event or an array of events.
• jobs: A group of tasks called jobs. Jobs run in parallel by default but can be configured to run sequentially.

Triggering Events (on)

• Push: Triggers the workflow on a push event.
  • Example: on: push
• Pull Request: Triggers the workflow on a pull request event.
  • Example: on: pull_request
• Scheduled Events: Triggers the workflow at scheduled times.
  • Example: on: schedule: - cron: '*/15 * * * *'
• Manual Trigger: Allows the workflow to be manually triggered.
  • Example: on: workflow_dispatch

Permissions

Permissions are defined at the workflow or job level, allowing you to control the scope of access for GitHub tokens. The permissions syntax lets you specify which permissions your workflow requires for accessing repository resources.

The following permissions can be configured:

• actions: Read/write permissions for GitHub Actions.
• checks: Read/write permissions for checks.
• contents: Read/write permissions for repository contents.
• deployments: Read/write permissions for deployments.
• issues: Read/write permissions for issues.
• packages: Read/write permissions for GitHub Packages.
• pull-requests: Read/write permissions for pull requests.
• repository-projects: Read/write permissions for repository projects.
• security-events: Read/write permissions for security events.
• statuses: Read/write permissions for commit statuses.

Jobs

• runs-on: Specifies the type of machine to run the job on.
• steps: A sequence of tasks that will be executed as part of the job.
• needs: Specifies jobs that need to complete before this job runs.

Steps

• name: A name for the step to display in the GitHub UI.
• uses: Selects an action to run as part of the step.
• run: Runs command-line programs using the operating system’s shell.
• env: Sets environment variables for the step.

Actions (uses)

• Official actions (e.g., actions/checkout@v2) or custom actions can be used.
• Actions are reusable units of code that can be shared within a repository or with the GitHub community.

Environment Variables (env)

• Global environment variables can be defined for the entire workflow or specifically for individual jobs or steps.

Example Workflow

name: CI

on: [push, pull_request]

permissions:
  contents: read
  issues: write

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write

    steps:
    - uses: actions/checkout@v2

    - name: Run a one-line script
      run: echo Hello, world!

    - name: Run a multi-line script
      run: |
        echo Add other commands here
        echo This is a multi-line script