GitHub Actions

What is GitHub Actions?

GitHub Actions is a powerful automation tool that allows you to build, test, and deploy your projects directly from your GitHub repository. In this guide, I'll take you through the basics of GitHub Actions, providing hands-on examples to help you get started.

1. Basic Building Blocks & Components

At its core, GitHub Actions revolves around three main components: Workflows, Jobs, and Steps. Workflows define the automated processes, while Jobs represent the individual tasks within a workflow. Steps, in turn, are the smallest units of work, executing commands or actions.

Let's create a simple workflow that runs whenever you push code to the main branch. Create a file named .github/workflows/main.yml in your repository:

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

In this example:

• Workflow: The entire CI/CD process is defined within the main.yml file.
• Job (build): Represents a set of tasks. In this case, it runs on the latest version of Ubuntu.
• Steps: Individual units of work, such as checking out the repository, setting up Node.js, installing dependencies, and running tests.

This workflow checks out your code, sets up Node.js, installs dependencies, and runs tests.

2. Using Events to Trigger Workflows

Workflows kick off based on specific events, such as pushes, pull requests, or issue creation.

Modify your workflow to trigger on both push and pull requests:

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

Now, your workflow runs on every push to main and every pull request.

3. Job Artifacts & Outputs

Job artifacts allow you to persist data between jobs in a workflow, enabling seamless sharing of results.

1jobs:
2  build:
3    runs-on: ubuntu-latest
4
5    steps:
6    - name: Build application
7      run: npm run build
8
9    - name: Archive build artifacts
10      uses: actions/upload-artifact@v2
11      with:
12        name: my-app
13        path: build/

This job builds the application, and the actions/upload-artifact step archives the build/ directory.

4. Using Environment Variables & Secrets

Security is paramount in automation. GitHub Actions allows you to use environment variables and secrets to safeguard sensitive information. For example, set up an environment variable for a deployment token:

1jobs:
2  deploy:
3    runs-on: ubuntu-latest
4    env:
5      DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
6
7    steps:
8    - name: Deploy to production
9      run: deploy-script.sh

Define DEPLOY_TOKEN in your repository's secrets for secure access.

5. Controlling Workflow & Job Execution

Fine-tune your workflows by controlling when and how they run. Explore strategies for workflow and job execution control, including conditional expressions and matrix builds, optimizing your CI/CD processes.

Fine-tune your workflows with conditional expressions:

1# .github/workflows/main.yml
2
3jobs:
4  build:
5    runs-on: ubuntu-latest
6
7    steps:
8    - name: Run on main branch
9      run: echo "Running on main branch"
10      if: github.ref == 'refs/heads/main'

This example runs the step only if the branch is main.

Matrix builds allow you to run a workflow against multiple configurations in parallel. For example, test your application on different Node.js versions:

1jobs:
2  test:
3    runs-on: ubuntu-latest
4    strategy:
5      matrix:
6        node-version: [14, 16]
7
8    steps:
9    - name: Set up Node.js
10      uses: actions/setup-node@v3
11      with:
12        node-version: ${{ matrix.node-version }}
13
14    - name: Install dependencies
15      run: npm install
16
17    - name: Run tests
18      run: npm test

This workflow tests your application on both Node.js 14 and 16.

6. Jobs & Docker Containers

GitHub Actions seamlessly integrates with Docker, allowing you to define jobs that run in Docker containers. For instance, run a job in a Node.js 14 Docker container:

1jobs:
2  build:
3    runs-on: ubuntu-latest
4    container:
5      image: node:14
6
7    steps:
8    - name: Checkout repository
9      uses: actions/checkout@v2
10
11    - name: Install dependencies
12      run: npm install

This job runs in a Node.js 14 Docker container, ensuring a consistent environment.

7. Building & Using Custom Actions

Create custom actions to encapsulate and reuse common pieces of automation. For example, a custom action to notify on Slack:

1jobs:
2  notify:
3    runs-on: ubuntu-latest
4
5    steps:
6    - name: Notify on Slack
7      uses: my-org/slack-notification-action@v1
8      with:
9        slack-token: ${{ secrets.SLACK_TOKEN }}
10        message: "Build successful!"

You can define this custom action in a separate repository and reference it in your workflows.

8. Security & Permissions

Follow security best practices when working with GitHub Actions. Avoid exposing sensitive information in logs, use secrets for confidential data, and limit permissions. For example, only run a deploy step if the actor is a trusted user:

1jobs:
2  deploy:
3    runs-on: ubuntu-latest
4    if: github.actor == 'trusted-user'
5
6    steps:
7    - name: Deploy to production
8      run: deploy-script.sh

This example runs a secure step only if the GitHub actor is an authorized user.

Wrap Up

GitHub Actions empowers developers with a flexible and integrated automation platform, fostering collaboration and enhancing development workflows. As you navigate the various components, events, and features, remember to tailor your automation to your team's unique needs, striking the perfect balance between efficiency and security. By mastering GitHub Actions, you unlock the potential for streamlined, reliable, and automated software development processes in your GitHub repositories.