Use Forge in CI

Forge automatically detects CI environments and activates in ephemeral mode — no seat is reserved, and the activation is gone when the runner terminates.

You need one repository secret: FORGE_LICENSE_KEY.

Ephemeral mode

When Forge detects a CI environment (CI=true plus a vendor-specific variable), it skips machine fingerprint binding entirely. Your CI pipelines can run on any number of parallel runners without burning through seats. All ephemeral usage is logged in the admin portal for your records.

GitHub Actions

.github/workflows/forge-check.yml

name: Forge health check

on:
  push:
    branches: [main]
  pull_request:

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

      - name: Install Forge
        run: |
          curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
          echo "$HOME/.forge/bin" >> "$GITHUB_PATH"

      - name: Activate license (ephemeral — no seat consumed)
        run: forge activate "$FORGE_LICENSE_KEY"
        env:
          FORGE_LICENSE_KEY: ${{ secrets.FORGE_LICENSE_KEY }}

      - name: Run health check
        run: forge health --repo .

Forge detects GITHUB_ACTIONS=true automatically. No extra configuration needed.

GitLab CI

.gitlab-ci.yml

forge-check:
  image: ubuntu:24.04
  variables:
    # FORGE_LICENSE_KEY is a protected CI/CD variable set in Settings → CI/CD → Variables
    FORGE_LICENSE_KEY: $FORGE_LICENSE_KEY
  script:
    - curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
    - export PATH="$HOME/.forge/bin:$PATH"
    - forge activate "$FORGE_LICENSE_KEY"
    - forge health --repo .

CircleCI

.circleci/config.yml

version: 2.1
jobs:
  forge-check:
    docker:
      - image: cimg/base:2024.01
    steps:
      - checkout
      - run:
          name: Install and activate Forge
          command: |
            curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
            echo 'export PATH="$HOME/.forge/bin:$PATH"' >> "$BASH_ENV"
      - run:
          name: Run Forge health check
          command: |
            forge activate "$FORGE_LICENSE_KEY"
            forge health --repo .

Store FORGE_LICENSE_KEY in CircleCI’s Project Settings → Environment Variables.

Buildkite

pipeline.yml

steps:
  - label: "Forge health check"
    command:
      - curl -fsSL https://downloads.forge.ironpinelabs.com/install.sh | sh
      - export PATH="$HOME/.forge/bin:$PATH"
      - forge activate "$$FORGE_LICENSE_KEY"
      - forge health --repo .
    env:
      FORGE_LICENSE_KEY: # Set in Buildkite's environment hooks or Pipeline secrets

Overrides

Variable	Effect
FORGE_EPHEMERAL=1	Force ephemeral mode (useful for testing)
FORGE_EPHEMERAL=0	Force persistent mode even in CI (seat IS consumed)

Setting FORGE_EPHEMERAL=0 is the escape hatch if you run a persistent long-lived CI agent that should own a dedicated seat.