GitHub Actions

This page explains how to integrate HoundDog.ai’s code scanner with GitHub Actions.

Defining GitHub Action Secrets

First, follow the steps in API Keys to generate a HoundDog.ai organization API key. Then follow the instructions in the GitHub documentation to create a new secret named HOUNDDOG_API_KEY using the value of your key.

Defining the Workflow in hounddog.yml

Next, add a new GitHub Actions workflow file named .github/workflows/hounddog.yml in your repository. Here is an example which scans your repository and uploads the results to the HoundDog.ai Cloud Platform:

name: Run HoundDog.ai Scan
on:
  push:
    branches: ["main"]
jobs:
  scan:
    name: Run HoundDog.ai Scan
    runs-on: ubuntu-latest
    permissions:
      contents: read
    container:
      image: hounddogai/hounddog
      options: --pull=always
    # Skip runs triggered by dependabot to avoid permission issues.
    if: github.actor != 'dependabot[bot]'
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run HoundDog.ai scan
        env:
          HOUNDDOG_API_KEY: ${{ secrets.HOUNDDOG_API_KEY }}
        run: hounddog scan
        continue-on-error: true

Here is another example for users who prefer to manage their findings in GitHub Advanced Security using the SARIF output format:

name: Run HoundDog.ai Scan
on:
  push:
    branches: ["main"]
jobs:
  scan:
    name: Run HoundDog.ai Scan
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    container:
      image: hounddogai/hounddog
      options: --pull=always
    # Skip runs triggered by dependabot to avoid permission issues.
    if: github.actor != 'dependabot[bot]'
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run HoundDog.ai scan
        env:
          HOUNDDOG_API_KEY: ${{ secrets.HOUNDDOG_API_KEY }}
        run: hounddog scan --output-format=sarif --output-path=hounddog.sarif --no-cloud-upload
        continue-on-error: true

      - name: Upload results to GitHub Advanced Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: hounddog.sarif
        continue-on-error: true

Blocking the Workflow Upon Detecting Vulnerabilities

In the examples above, continue-on-error: true keeps the workflow green regardless of the scan outcome. To fail the workflow upon detecting vulnerabilities, remove continue-on-error and provide the --fail-severity-threshold option to the hounddog scan command:

name: Run HoundDog.ai Scan
on:
  push:
    branches: ["main"]
jobs:
  scan:
    name: Run HoundDog.ai Scan
    runs-on: ubuntu-latest
    permissions:
      contents: read
    container:
      image: hounddogai/hounddog
      options: --pull=always
    # Skip runs triggered by dependabot to avoid permission issues.
    if: github.actor != 'dependabot[bot]'
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run HoundDog.ai scan
        env:
          HOUNDDOG_API_KEY: ${{ secrets.HOUNDDOG_API_KEY }}
        # Fail if a risky dataflow with severity "medium" or higher is detected.
        run: hounddog scan --fail-severity-threshold=medium

The scan results still upload to the Cloud Platform before the job fails, so the platform always reflects the latest scan.

To view all available command-line options for the hounddog scan command, see Scanner Configuration.