4 minute read

GitHub Actions is a powerful CI/CD (Continuous Integration/Continuous Delivery) tool that allows you to automate workflows directly within your GitHub repository. This guide will walk you through the basics of setting up GitHub Actions for a CI/CD pipeline to test, build, and deploy your project.

What is CI/CD?

Before diving into GitHub Actions, let’s define CI/CD:

  • Continuous Integration (CI) is the practice of automatically testing and merging code changes frequently to prevent integration issues.
  • Continuous Delivery (CD) automates the deployment of code to production or staging environments, ensuring every code change is ready to be deployed.

GitHub Actions makes it easy to automate these workflows by offering a simple YAML-based configuration.

Step 1: Create a GitHub Repository

  1. Go to GitHub and create a new repository or use an existing one.
  2. Clone the repository to your local machine: 
    git clone https://github.com/your-username/your-repository.git

Step 2: Setting Up a Basic GitHub Actions Workflow

  1. In your project root directory, create a folder called .github/workflows if it doesn’t already exist: 
    mkdir -p .github/workflows
  2. Inside the workflows folder, create a YAML file for your CI pipeline, e.g., ci.yml: 
    touch .github/workflows/ci.yml
  3. Open the file and define your basic workflow. Here’s an example that runs tests on push and pull requests: 
    name: CI Pipeline

# Run workflow on push or pull requests to the main branch
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      # This step fetches your code from the repository.
      uses: actions/checkout@v3
      # 'uses' is a special command in GitHub Actions that allows you to use pre-built actions from the GitHub Actions Marketplace.
      # Learn more about it here: https://github.com/actions/checkout

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

    - name: Install dependencies
      run: |
        npm install

    - name: Run tests
      run: |
        npm test

Explanation of Key Parts:

  • uses: actions/checkout@v3: This action checks out your repository so the workflow can access your code. It’s a common first step in many workflows.
    • More details about this action can be found here.
  • uses: actions/setup-node@v3: This action sets up a specific version of Node.js. If you’re working with JavaScript or any Node-based project, this step ensures the correct environment is ready.
  • npm install: This installs your project’s dependencies as listed in your package.json file.
  • npm test: This runs the tests defined in your project. If you don’t have a test setup, you can skip this step or create simple tests to get started.

If your project uses another language, such as Python or Ruby, replace the relevant setup and installation commands with the corresponding ones.

Step 3: Commit and Push Your Workflow

  1. Save your workflow and commit the changes to your repository: 
    git add .github/workflows/ci.yml
git commit -m "Add GitHub Actions CI workflow"
git push origin main
  2. Go to your GitHub repository and navigate to the Actions tab. You’ll see your workflow running automatically whenever you push or open a pull request to the main branch.

Step 4: Extending the Workflow for CD (Deployment)

Let’s extend the workflow to include a deployment step. For simplicity, we’ll use GitHub Pages to deploy a static website, but this concept applies to other deployment services.

  1. Modify your ci.yml file to include a deployment step after testing:

    name: CI/CD Pipeline

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

jobs:
  test:
    runs-on: ubuntu-latest

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

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

    - name: Install dependencies
      run: |
        npm install

    - name: Run tests
      run: |
        npm test

  deploy:
    needs: test  # Only deploy if tests pass
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Deploy to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: $
        publish_dir: ./public

Explanation of Deployment:

  • needs: test: This ensures that the deployment step only runs if the tests pass.
  • peaceiris/actions-gh-pages@v3: This is a pre-built action that automatically deploys to GitHub Pages. It uses the GITHUB_TOKEN, which GitHub generates for the workflow to authenticate and push the site. In this example, we use an action developed by ‘peaceiris’ to demonstrate that anyone can create and share custom actions on GitHub.
  • publish_dir: This is the directory where your static website files are generated. If you’re using a static site generator like Jekyll or Hugo, this would be the folder containing your built site (e.g., _site for Jekyll or public for Hugo).

Step 5: Monitoring and Debugging

  • After every push or pull request, GitHub Actions will display the status of your workflows under the Actions tab.
  • You can view the logs of each step to debug any issues if the workflow fails.

Conclusion

You now have a working CI/CD pipeline using GitHub Actions! This basic setup runs tests on every push and pull request, and it deploys a static website to GitHub Pages automatically when the tests pass. You can further extend this setup by adding more jobs, steps, or platform-specific deployments.

Further Reading:

You may also enjoy