> ## Documentation Index
> Fetch the complete documentation index at: https://pentest-tools.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Integrate security scanning into your GitHub Actions workflows

The GitHub Actions integration lets you run Pentest-Tools.com scans as part of your CI/CD pipeline.

<Info>
  Available on **WebNetSec** and **Pentest Suite** plans.
</Info>

## Benefits

<CardGroup cols={2}>
  <Card title="Shift left security" icon="shield-check">
    Catch vulnerabilities before they reach production.
  </Card>

  <Card title="Automated testing" icon="robot">
    Run security scans automatically on every push or PR.
  </Card>

  <Card title="Fail conditions" icon="circle-xmark">
    Fail builds when vulnerabilities exceed your threshold.
  </Card>

  <Card title="Flexible output" icon="file-export">
    Get results in text or JSON format.
  </Card>
</CardGroup>

## Setting up GitHub Actions

<Steps>
  <Step title="Create an action">
    Go to Settings > Integrations > GitHub Actions and click Create action.
  </Step>

  <Step title="Configure the action">
    Set the target, scan type, output format, fail condition, and the name of the GitHub secret that will hold your Pentest-Tools API key.
  </Step>

  <Step title="Add your API key to GitHub Secrets">
    In your GitHub repository, go to Settings > Secrets and variables > Actions. Add your Pentest-Tools API key using the secret name from step 2.
  </Step>

  <Step title="Add to your workflow">
    Copy the generated YAML and add it to a file in `.github/workflows/`.
  </Step>
</Steps>

## Action configuration

| Setting            | Description                                                             |
| ------------------ | ----------------------------------------------------------------------- |
| **Name**           | A descriptive name for the action                                       |
| **Target**         | The URL or IP to scan                                                   |
| **Scan type**      | `light` or `deep`                                                       |
| **Output format**  | `text` or `json`                                                        |
| **Fail condition** | Severity threshold to fail the build                                    |
| **Secret name**    | Name of the GitHub repository secret holding your Pentest-Tools API key |

### Fail conditions

Configure when your pipeline should fail:

| Condition | Build fails when...             |
| --------- | ------------------------------- |
| None      | Never fails based on findings   |
| Low       | Low or higher severity found    |
| Medium    | Medium or higher severity found |
| High      | High or higher severity found   |
| Critical  | Critical severity found         |

## Example workflow

The integration generates a YAML snippet using the `pentesttoolscom/pentesttools-github-action` action. Add it to a file in `.github/workflows/`. The action handles scan execution and output. No polling required.

```yaml theme={null}
jobs:
  test_deep_scan:
    runs-on: ubuntu-latest
    name: Run a deep scan.
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Run scan
        uses: pentesttoolscom/pentesttools-github-action@master
        id: ptt
        with:
          target: https://your-website.com
          format: text
          fail: high
          type: deep
          key: ${{ secrets.PTT_API_KEY }}
      - name: Print result
        run: echo "${{ steps.ptt.outputs.result }}"

on:
  schedule:
    - cron: '0 0 * * *'
  pull_request:
```

The `key` references the GitHub repository secret you configured. Set `fail` to the severity level that should fail the build: `high` means the job fails if any high or critical findings are found.

## Scan types

| Type      | Description                      | Use Case                        |
| --------- | -------------------------------- | ------------------------------- |
| **Light** | Fast reconnaissance scan         | Quick checks, PR validation     |
| **Deep**  | Comprehensive vulnerability scan | Pre-production, scheduled scans |

<Tip>
  Use Light scans for PR validation to keep CI times short, and schedule Deep scans for nightly or weekly runs.
</Tip>

## Output formats

### Text output

Human-readable summary of findings, ideal for quick review in logs.

### JSON output

Structured data for programmatic processing:

```json theme={null}
{
  "scan_id": 12345,
  "target": "example.com",
  "findings": [
    {
      "title": "SQL Injection",
      "severity": "high",
      "description": "..."
    }
  ]
}
```

## Best practices

<Warning>
  Store your action secret in GitHub Secrets, never commit it to your repository.
</Warning>

* Use fail conditions appropriate to your pipeline stage
* Run Light scans on PRs, Deep scans on main branch
* Review findings before merging, even if build passes
* Set up notifications for failed security checks

## Troubleshooting

<AccordionGroup>
  <Accordion title="Scan not running">
    * Verify the action secret is correct
    * Check that the action exists and is enabled
    * Review GitHub Actions logs for errors
  </Accordion>

  <Accordion title="Build failing unexpectedly">
    * Review the fail condition setting
    * Check if findings meet the threshold
    * Verify the target is accessible
  </Accordion>
</AccordionGroup>

## Related topics

* [Generic CI/CD](/docs/capabilities/integrations/generic-cicd)
* [API overview](/docs/api-reference)
* [Notifications](/docs/capabilities/notifications)