Github Actions

GitHub Actions Standards

GitHub Actions is a powerful CI/CD tool integrated with GitHub that allows you to automate workflows directly from your repository. Following standards and best practices ensures that your workflows are maintainable, efficient, and secure.

Basic Structure of a Workflow

A GitHub Actions workflow is defined in a YAML file located in the .github/workflows directory of your repository. Here’s a basic structure of a workflow file:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '14'

      - name: Install dependencies
        run: npm install

      - name: Run tests
        run: npm test

Naming Conventions

• Workflow Files: Use descriptive names for your workflow files. For example, ci.yml for continuous integration, deploy.yml for deployment, etc.

• Job and Step Names: Use clear and descriptive names for jobs and steps to make the workflow easy to understand.

Triggering Workflows

• Use specific events to trigger workflows, such as push, pull_request, or schedule.

• Specify branches to control where the workflows run (e.g., only on main or specific feature branches).

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

Jobs and Steps

• Modular Jobs: Break down workflows into multiple jobs if they perform distinct tasks (e.g., build, test, deploy).

• Reusable Steps: Use reusable steps to avoid duplication and improve maintainability.

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      # Additional steps

Caching Dependencies

Use caching to speed up your workflows by caching dependencies. For example, caching node_modules in a Node.js project:

- name: Cache dependencies
  uses: actions/cache@v2
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

Secrets Management

• Use GitHub Secrets to store sensitive information like API keys, tokens, and credentials.

• Reference secrets in your workflow using ${{ secrets.SECRET_NAME }}.

- name: Deploy
  run: npm run deploy
  env:
    API_KEY: ${{ secrets.API_KEY }}

Best Practices

• Lint YAML Files: Ensure your workflow YAML files are correctly formatted and linted.

• Error Handling: Add error handling to steps to make workflows robust.

• Notifications: Set up notifications for workflow status to stay informed about failures or important events.

Example Workflow with Best Practices

name: CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '14'

      - name: Cache dependencies
        uses: actions/cache@v2
        with:
          path: node_modules
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - name: Install dependencies
        run: npm install

      - name: Lint code
        run: npm run lint

      - name: Run tests
        run: npm test

      - name: Build project
        run: npm run build

      - name: Deploy
        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
        run: npm run deploy
        env:
          API_KEY: ${{ secrets.API_KEY }}

By adhering to these standards and best practices, you can create efficient, maintainable, and secure workflows with GitHub Actions.