Skip to main content
FOSSA Logo

GitHub Actions CI/CD: Setup, Best Practices, and FOSSA Integration

Technical guide on setting up GitHub Actions CI/CD pipelines, covering workflow basics, caching, matrix builds, secrets management, artifact storage, and integrating FOSSA for license compliance / vulnerability management.

Contents

About

GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that automates build, test, and deployment pipelines. It serves as a general-purpose DevOps automation tool, enabling workflows for not only CI/CD but also other repository events (for example, automatically labeling new issues or running scheduled tasks). GitHub Actions workflows run on managed virtual machines (runners) provided by GitHub for Linux, Windows, and macOS, or on self-hosted runners in custom environments. These workflows are triggered by events like pushes, pull requests, issue creation, or cron schedules, and consist of jobs with sequential steps that execute commands or reusable actions.

An event triggers a GitHub Actions workflow, running Job 1 and Job 2 on separate runners. Each job contains multiple steps (running actions or scripts) executed in order.

Key capabilities of GitHub Actions include:

  • Event-driven workflows – Workflows defined in YAML files within the .github/workflows/ directory automatically run when triggered by specified events, allowing you to implement CI/CD pipelines that run on each commit or on a schedule. You can learn more in the GitHub Docs on understanding GitHub Actions.
  • Isolated runner environments – Each job runs on a fresh virtual machine or container, ensuring reproducibility. Runners come with common languages and tools pre-installed, and support installing any needed dependencies.
  • Parallel and sequential jobs – Workflows can orchestrate multiple jobs. By default jobs run in parallel, or can be sequenced with dependencies. For example, a build job can fan-out into parallel test jobs on multiple platforms, then fan-in to a deploy job once tests pass.
  • Reusable actions – Common tasks like checking out code, setting up languages, or uploading artifacts are packaged as actions. Workflows can use community-maintained or custom actions to avoid writing repetitive script code, improving maintainability.

GitHub Actions thus provides a flexible CI/CD system that scales from simple build/test automation to complex DevOps pipelines, all defined as code in the repository.

Setup Guide

Setting up GitHub Actions for a project involves creating a workflow file and defining the steps to build and test the code. Workflows are defined in YAML and stored in the repository (for example, .github/workflows/ci.yml). Below is a minimal but complete CI workflow example that runs on every push and pull request to the main branch, installing dependencies, building the project, and running tests:

name: CI
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3    # Fetch repository code
      - name: Set up Node.js         # Set up runtime (using Node.js as example)
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      - name: Install dependencies
        run: npm ci
      - name: Build project
        run: npm run build
      - name: Run tests
        run: npm test

In this workflow:

  • Triggers are defined under on: it runs for any push or pull request to the main branch.
  • Job "build-and-test" runs on the latest Ubuntu runner, which provides a clean Linux VM for the job.
  • The job's steps use standard actions and shell commands:
    • actions/checkout@v3 retrieves the repository content onto the runner (since each job starts with a fresh environment, checking out the code is required).
    • actions/setup-node@v3 configures Node.js 16 on the runner (many official setup actions exist for different languages/runtime environments).
    • The remaining steps run shell commands to install project dependencies, build the software, and execute tests. If any of these steps fails (returns a non-zero exit code), the job (and thus the workflow) will be marked as failed.

This minimal setup provides a continuous integration pipeline: every commit triggers a clean build and test run. It can be extended with additional jobs or steps as needed.

Ongoing Usage

After getting a basic workflow running, teams often refine their GitHub Actions setup to improve efficiency and cover more scenarios. Key practices and features for ongoing usage include:

  • Caching: Speed up subsequent workflow runs by caching dependencies and build outputs. GitHub's official cache action allows saving files (for example, language package caches like node_modules or .m2 for Maven) keyed by checksum. On a cache hit, the workflow restores these files instead of re-downloading them, significantly reducing build time. Many setup actions also integrate caching out-of-the-box.
  • Matrix builds: Test against multiple environments in one workflow using a matrix strategy. A job matrix will run the same job in parallel for different configurations (e.g. multiple OSes or language versions). For example, a matrix can run a test job on Ubuntu, Windows, and macOS or against Node.js versions 14, 16, and 18 simultaneously. This ensures broader coverage (catching OS or version-specific issues) without writing separate workflows.
  • Secrets management: Store sensitive values securely in GitHub repository or organization settings and access them in workflows via the secrets context. For example, a deployment key can be set as MY_API_KEY in repository secrets, and referenced in the workflow as ${{ secrets.MY_API_KEY }}. This keeps sensitive information out of the codebase and logs, while allowing workflows to use them as environment variables or action inputs.
  • Artifact storage: Persist build outputs and test results by uploading them as artifacts with the actions/upload-artifact action. These artifacts can be downloaded later from the GitHub UI or used by subsequent jobs in the workflow. This is useful for preserving data across job boundaries or for developers to inspect results of CI runs.

Using with FOSSA

FOSSA is a tool for automating open source license compliance and vulnerability management (software composition analysis) in the development workflow. Integrating FOSSA into GitHub Actions adds continuous license and security scanning of your project's dependencies. This ensures that any problematic licenses or known vulnerable components are detected during CI, complementing your regular tests.

To set up GitHub Actions FOSSA integration in a CI/CD pipeline:

  1. Obtain a FOSSA API key – Generate an API token from the FOSSA platform (via the FOSSA account settings). This key will authorize the GitHub Action to upload scan results and fetch project info on FOSSA.

  2. Add the API key as a secret – In the GitHub repository settings, add a new repository secret (e.g. named FOSSA_API_KEY) with the value of the FOSSA API key. This keeps the key secure and available to the workflow.

  3. Update the workflow to run FOSSA – Incorporate a FOSSA scan job in the GitHub Actions workflow using FOSSA's official GitHub Action. The job should check out the code and then use the FOSSA action with the API key secret. For example, a dedicated job could be added to the workflow YAML as follows:

    jobs:
  fossa-scan:
    runs-on: ubuntu-latest
    needs: build-and-test           # ensure main build/test job completed successfully
    steps:
      - uses: actions/checkout@v3
      - name: FOSSA Scan
        uses: fossas/fossa-action@v1
        with:
          api-key: ${{ secrets.FOSSA_API_KEY }}
          run-tests: true

    In this snippet, the FOSSA scan job runs after the primary build/test job (needs: build-and-test). It uses the FOSSA Action to scan the project for license and security issues using the provided API key. Setting run-tests: true tells FOSSA to not only scan but also fail the workflow if an issue violating policy is found (this triggers the FOSSA CLI's fossa test mode, causing the job to error out for license policy or vulnerability findings). The FOSSA action automatically downloads the latest FOSSA CLI, uses the API key to access the project configuration, and uploads scan results to the FOSSA platform.

Integrating FOSSA into GitHub Actions adds an important layer to the CI/CD pipeline:

  • License compliance checks ensure that all open-source licenses in the dependency chain are compatible with the project's licensing requirements. If a forbidden license is introduced, the FOSSA job can catch it before the code is merged, avoiding legal or policy violations.
  • Vulnerability scanning catches known security issues in dependencies. FOSSA's continuously updated database flags libraries with CVEs, so the CI can alert or fail on high-severity vulnerabilities. This proactive approach aligns with "shift-left" security – finding and fixing issues early in development rather than after release.
  • Compliance reports and governance – FOSSA's integration can produce an inventory of dependencies (an SBOM) and compliance reports every build. This provides maintainers and security teams with up-to-date insight into third-party software usage. Over time, it helps track and remediate risk as new vulnerabilities are disclosed or license requirements change.

By using GitHub Actions together with FOSSA, engineering teams achieve a more robust CI/CD setup: every code change is not only built and tested, but also vetted for open source license compliance and security risks. This automation enhances the DevOps pipeline with continuous CI (integration), CD (delivery), and now continuous compliance, ensuring higher software quality and reduced risk in dependencies.