GitHub Actions

Integrating regis-cli into your GitHub Actions workflows allows you to automate security and compliance checks for every container image you build. This ensures that only images meeting your predefined standards are promoted through your pipeline.

Prerequisites

To follow this guide, you should have a GitHub repository with a Dockerfile and a basic understanding of GitHub Actions.

tip

To quickly bootstrap a new GitHub repository pre-configured with regis-cli and GitHub Actions, you can use our Project Bootstrapping command.

Workflow Setup

A robust integration typically involves building your image, pushing it to a registry (like GitHub Container Registry), and then running regis-cli to analyze the results.

Required Permissions

Ensure your workflow has the necessary permissions to read content and write to the package registry:

permissions:
  contents: read
  packages: write

Complete Example

The following example demonstrates a complete workflow that builds an image, pushes it to GHCR, and performs a security analysis.

name: Build and Analyze

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

jobs:
  build-and-analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and push
        id: build
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:latest

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install regis-cli
        run: |
          pip install pipenv
          pipenv install --deploy

      - name: Run Analysis
        run: |
          pipenv run regis-cli analyze ghcr.io/${{ github.repository }}:latest \
            --auth ghcr.io:${{ github.actor }}:${{ secrets.GITHUB_TOKEN }} \
            --site \
            --meta "trigger.user=${{ github.actor }}" \
            --meta "trigger.url=${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: regis-security-report
          path: reports/

Publishing to GitHub Pages

You can host your security reports directly on GitHub Pages by adding a deployment job to your workflow.

Configure Repository

1. Go to Settings > Pages.
2. Under Build and deployment > Source, select GitHub Actions.

Deployment Job

Add the following job to your workflow to deploy the generated site:

deploy:
  environment:
    name: github-pages
    url: ${{ steps.deployment.outputs.page_url }}
  runs-on: ubuntu-latest
  needs: build-and-analyze
  permissions:
    pages: write
    id-token: write
  steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4
      with:
        artifact_name: github-pages # Matches the artifact uploaded by build-and-analyze

important

To use this job, update your Run Analysis step to use --site and ensure you use actions/upload-pages-artifact instead of upload-artifact in the build-and-analyze job.

- name: Upload Pages Artifact
  uses: actions/upload-pages-artifact@v3
  with:
    path: reports/

Advanced Configuration

You can further customize the integration to meet specific security requirements.

Authenticating with Private Registries

To analyze images in private registries, use the --auth flag. For GitHub Container Registry, you can use the automatically provided GITHUB_TOKEN.

regis-cli analyze <image-url> --auth ghcr.io:<username>:<token>

Using Security Playbooks

By default, regis-cli uses its built-in evaluation logic. For standardized security enforcement, you can point to the project's recommended security playbook.

regis-cli analyze <image-url> --playbook https://raw.githubusercontent.com/trivoallan/regis-cli/main/regis_cli/playbooks/default.yaml

tip

You can also define local playbooks in your repository to enforce custom organization-wide policies. Check the Playbooks guide for more details.

Adding CI Metadata

Use the --meta flag to attach arbitrary metadata to your reports. regis-cli recognizes certain "well-known" keys that are used by the default playbook to enhance the report:

• trigger.user: The user who initiated the analysis (e.g., ${{ github.actor }}).
• trigger.url: A link to the CI job or environment (e.g., the URL to the GitHub Actions run).

regis-cli analyze <image-url> \
  --meta "trigger.user=${{ github.actor }}" \
  --meta "trigger.url=${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"

Viewing Reports

When using the --site flag, regis-cli generates a full HTML site in the reports/ directory. By uploading this directory as a workflow artifact (as shown in the example), you can download and view the interactive reports directly from the GitHub Actions run page.