---
title: "GitHub Actions"
description: "Add DAST scanning to GitHub Actions with the HawkScan Action. Quick setup guide with workflow examples for automated security testing."
url: https://docs.stackhawk.com/integrations/ci-cd/github-actions/
---

# GitHub Actions

![GitHub](https://docs.stackhawk.com/images/integrations/logos/github.svg)

Add DAST scanning to your GitHub Actions workflows with the [HawkScan GitHub Action](https://github.com/marketplace/actions/stackhawk-hawkscan-action).

## Quick Start

1. Store your API key as a [GitHub secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) named `HAWK_API_KEY`
2. Add a workflow file at `.github/workflows/hawkscan.yml`
3. Configure HawkScan with a `stackhawk.yml` file

> **Note:** Looking for the **Microsoft Defender for Cloud** integration? [Check out the documentation here](https://docs.stackhawk.com/integrations/workflows/microsoft/defender-for-cloud/).

## Store Your API Key

Copy your StackHawk API key to a GitHub secret:

1. Go to your repository’s **Settings** tab
2. Click **Secrets and variables > Actions**
3. Add a new secret named `HAWK_API_KEY` with your API key value

## Basic Workflow Configuration

Create `.github/workflows/hawkscan.yml`:

```yaml
name: HawkScan

on:
  push:
  pull_request:

jobs:
  hawkscan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run HawkScan
        uses: stackhawk/hawkscan-action@v3
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}
```

## HawkScan Configuration

Create `stackhawk.yml` at your repository root:

```yaml
app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://example.com
  env: Development
```

Replace `applicationId` with your Application ID from StackHawk.

## Run Your Scan

Commit both files and push to GitHub. Monitor the workflow in the GitHub Actions console, then review results in StackHawk.

---

## Local Scanning

The basic example assumes a publicly accessible endpoint. For local testing, you can run your app directly on the GitHub Actions runner.

### Scanning a Service on Localhost

Launch your app on the runner and scan it at `localhost`. The HawkScan action automatically configures network access.

Example workflow running Nginx on port 8080:

```yaml
name: HawkScan

on:
  push:
  pull_request:

jobs:
  hawkscan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Start Nginx
        run: docker run --rm --detach --publish 8080:80 --name nginx_test nginx

      - name: Run HawkScan
        uses: stackhawk/hawkscan-action@v3
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}
```

Configure `stackhawk.yml` to target localhost:

```yaml
app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  host: http://localhost:8080
  env: Development
```

### Scanning with Docker Compose

Use Docker Compose for complex environments with multiple services. Publish your app’s port to make it accessible on localhost.

Example `docker-compose.yml`:

```yaml
version: "3.9"

services:
  myapp:
    image: myapp
    ports:
      - "8080:80"

  db:
    image: postgres
    restart: always
    ports:
      - "5432:5432"
```

HawkScan configuration:

```yaml
app:
  applicationId: xxxxxxxx-XXXX-xxxx-XXXX-xxxxxxxxxxxx
  env: Development
  host: http://localhost:8080
```

Workflow file:

```yaml
name: HawkScan

on:
  push:

jobs:
  hawkscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - run: docker compose up -d

      - uses: stackhawk/hawkscan-action@v3
        with:
          apiKey: ${{ secrets.HAWK_API_KEY }}
```

## Without the Action

The HawkScan Action is the simplest way to scan in GitHub Actions. If you’d rather install and run the `hawk` CLI yourself, for example to run other `hawk` commands in the same job, use the hawk CLI [install script](https://docs.stackhawk.com/stackhawk-cli/#install-with-a-script). The script doesn’t change the PATH, so the install step adds `hawk` to `$GITHUB_PATH`, which GitHub Actions applies to every later step in the job.

**Tab: Linux/macOS runners**

```yaml
name: HawkScan

on:
  push:

jobs:
  hawkscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install HawkScan
        run: |
          # Optional: pin a version (6.0.0 or later). Leave it unset to install the latest release.
          # export HAWK_INSTALL_VERSION=6.6.0
          curl -fsSL https://download.stackhawk.com/hawk/install.sh | sh
          echo "$HOME/.hawk/bin" >> "$GITHUB_PATH"

      - name: Run HawkScan
        run: hawk --api-key="${HAWK_API_KEY}" scan stackhawk.yml
        env:
          HAWK_API_KEY: ${{ secrets.HAWK_API_KEY }}
```

**Tab: Windows runners**

```yaml
name: HawkScan

on:
  push:

jobs:
  hawkscan:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install HawkScan
        shell: pwsh
        run: |
          # Optional: pin a version (6.0.0 or later). Leave it unset to install the latest release.
          # $env:HAWK_INSTALL_VERSION = '6.6.0'
          irm https://download.stackhawk.com/hawk/install.ps1 | iex
          Add-Content -Path $env:GITHUB_PATH -Value "$env:USERPROFILE\.hawk\bin"

      - name: Run HawkScan
        shell: pwsh
        run: hawk --api-key="$env:HAWK_API_KEY" scan stackhawk.yml
        env:
          HAWK_API_KEY: ${{ secrets.HAWK_API_KEY }}
```

## Next Steps

- [HawkScan Action on GitHub Marketplace](https://github.com/marketplace/actions/stackhawk-hawkscan-action) for configuration options
- [GitHub Code Scanning Integration](https://docs.stackhawk.com/integrations/ci-cd/github-actions/github-code-scanning/) for GitHub Advanced Security