GitHub Actions Workflow YAML for Firefly Integration

To illustrate how Firefly integrates into CI, here's a snippet of a GitHub Actions workflow that runs Terraform and includes Firefly's workflow agent:

name: InfraCI
on:
  push:
    branches: [ main ]
jobs:
  terraform-deploy:
    runs-on: ubuntu-latest
    env:
      # AWS credentials provided as GitHub secrets
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      AWS_DEFAULT_REGION: us-east-1
    steps:
    - name: Checkout
      uses: actions/checkout@v3
    
    - name: Setup Terraform
      uses: hashicorp/setup-terraform@v1
    
    - name: Terraform Init
      run: terraform init
    
    - name: Terraform Plan
      # Generate and save the Terraform plan
      run: terraform plan -out=tfplan.binary
    
    - name: Firefly - Post Plan Scan
      # Using Firefly's docker agent to scan the plan
      run: |
        docker run --rm \
          -e FIREFLY_ACCESS_KEY=${{ secrets.FIREFLY_ACCESS_KEY }} \
          -e FIREFLY_SECRET_KEY=${{ secrets.FIREFLY_SECRET_KEY }} \
          -e CI_COMMIT_AUTHOR="${{ github.actor }}" \
          -v ${{ github.workspace }}:/workspace \
          gofireflyio/workflows-agent:latest \
          post-plan --workspace "Prod-Infra" --plan-file "/workspace/tfplan.binary" --wait
    # The --wait flag ensures the agent waits for the scan to complete and returns exit code if guardrail violation found.
    
    - name: Terraform Apply
      # Only proceed if no guardrail violations were found
      if: success()   # Only apply if previous step succeeded (no guardrail blocks)
      run: terraform apply -auto-approve tfplan.binary
    
    - name: Firefly - Post Apply
      # Report apply results to Firefly
      if: success()
      run: |
        docker run --rm \
          -e FIREFLY_ACCESS_KEY=${{ secrets.FIREFLY_ACCESS_KEY }} \
          -e FIREFLY_SECRET_KEY=${{ secrets.FIREFLY_SECRET_KEY }} \
          -v ${{ github.workspace }}:/workspace \
          gofireflyio/workflows-agent:latest \
          post-apply --workspace "Prod-Infra" --apply-log-file "/workspace/terraform.log"

Explanation:

We define a GitHub Actions job that runs on push to main (typical for an infra repo deploying automatically).

It sets AWS credentials via GitHub secrets (in practice, you might use OIDC and roles instead, but this is fine for example).

It runs Terraform init and plan. The plan is saved to tfplan.binary.

Firefly Post Plan step: This uses Firefly's workflow agent Docker image. It passes the Firefly API Access and Secret keys (retrieved from GitHub secrets – these keys you would get from Firefly's integration setup for CI).

It also passes some environment info like CI_COMMIT_AUTHOR – Firefly can record who initiated the run.

It mounts the repo into /workspace in the container so the agent can read the plan file.

It runs post-plan command with:

• --workspace "Prod-Infra": The name of the workspace configured in Firefly. This ties the plan to that logical group.

• --plan-file pointing to the plan output.

• --wait: important, it waits for guardrail scanning to finish on Firefly side. If any guardrail is violated and in Strict mode, the agent will exit with non-zero, causing the GitHub Action step to fail.

The if: success() on the Apply step ensures that if Firefly scan flagged something (thus marking previous step as failed), we do not proceed to apply.

Then after apply, another Docker run post-apply to report the results (this helps Firefly update state, cost calculations, etc., but the main gating was in post-plan).

Usage in Firefly:

You would have set up the workspace "Prod-Infra" in Firefly, and given the agent the keys via secrets as shown.

In Firefly UI, under Workflows, you'll now see runs for "Prod-Infra" whenever this pipeline triggers. If a run fails due to guardrails, you can click into it in Firefly and see which guardrail and why.

If you override a guardrail in Firefly, likely Firefly will instruct the agent to proceed (the agent might poll with --wait to get an override signal).

Customizing:

• For other CI systems, the concept is similar: run Firefly's agent container or binary after plan and after apply.

• You can also integrate as a Terraform Cloud run task (which would avoid you needing to manage a container in GitHub Actions).

• Ensure the Docker image version (latest here) is compatible with your Firefly version; you might pin a version tag.

This snippet demonstrates how code and Firefly integrate to create an automated, governed pipeline.