Skip to main content

Installation

Installing Bullfrog in your GitHub Actions workflow is straightforward. This guide will walk you through the process.

Quick Start​

Add Bullfrog as the first step in your job. This is crucial for Bullfrog to intercept all network traffic.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # This must be the first step
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2

      # Your other steps follow
      - uses: actions/checkout@v4
      - name: Build
        run: npm install && npm run build

Why First Step?​

We generally recommend making Bullfrog the first step in your job so it can set up network filtering before any other step executes. This ensures all outbound connections are monitored and controlled.

However, there are edge cases where you might intentionally run steps before Bullfrog:

  • Dynamic IP allowlisting: Fetching IP addresses that need to be allowed in your Bullfrog configuration
  • Unrestricted commands: Running commands that require wide IP ranges or domains that you don't want to open for subsequent steps

In these cases, Bullfrog will only monitor and control network traffic for steps that run after it. Any steps that run before Bullfrog will not be subject to its network filtering.

Supported Runners​

Bullfrog currently supports GitHub-hosted runners running Ubuntu:

  • ubuntu-latest
  • ubuntu-24.04
  • ubuntu-22.04
Limitations
  • Container Jobs: Jobs running in containers are not currently supported
  • Self-Hosted Runners: Only GitHub-hosted runners are supported
  • Windows/macOS: Only Ubuntu runners are supported

Pinning to a Specific Version​

For production workflows, we recommend pinning to a specific commit SHA for maximum security:

- uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2

This ensures your workflow uses an exact, verified version of Bullfrog.

Multiple Jobs​

Each job in a workflow runs in a separate runner environment. You must add Bullfrog as the first step in every job you want to protect:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
      - uses: actions/checkout@v4
      - run: npm run build

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
      - uses: actions/checkout@v4
      - run: npm test

  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: bullfrogsec/bullfrog@c8e5fff94e0050c0cef9b9596c55cf3d9c53ba2c # v0.9.2
      - uses: actions/checkout@v4
      - run: npm run deploy

Default Behavior​

By default, Bullfrog runs in audit mode, which logs all outbound connections without blocking them. This allows you to:

  1. Discover what connections your workflow makes
  2. Review the connections in the workflow summary
  3. Create an appropriate allow list
  4. Switch to block mode with confidence

See the Configuration page to learn how to customize Bullfrog's behavior.

Next Steps​