← Back to Documentation

GitHub Actions Setup

Schedule automated AWS audits that run weekly (or on demand) and upload the full report as a CI artifact. Two secrets, one workflow file — no Docker, no container registry.

Running StackSage interactively on your laptop? See the Quick Start guide instead — GitHub Actions is optional.

How it works

  1. GitHub Actions assumes a read-only IAM role in your AWS account via OIDC (no long-lived credentials).
  2. pip install stacksage runs in the runner — no Docker image or container registry needed.
  3. stacksage audit scans your account and writes the report to ./results/.
  4. The report is uploaded as a GitHub Actions artifact and retained for 30 days.

Prerequisites

  • A GitHub repo with Actions enabled
  • A StackSage Pro license key (STACKSAGE_LICENSE) — get one here
  • AWS account access to create an IAM role + OIDC trust policy (one-time, ~5 minutes)

Step 1 — Set up the IAM role

Create a read-only IAM role that GitHub Actions can assume via OIDC. See the IAM Policy Setup guide for the exact policy and trust relationship. The role ARN will look like: arn:aws:iam::123456789012:role/StackSageReadOnly

Step 2 — Add secrets to your repo

Go to Settings → Secrets and variables → Actions and add two secrets:

Secret nameValue
STACKSAGE_LICENSEYour license key (from your purchase confirmation email)
AWS_AUDIT_ROLE_ARNThe IAM role ARN from Step 1

Step 3 — Add the workflow file

Create .github/workflows/stacksage.yml in your repo:

name: StackSage Weekly Audit

on:
  schedule:
    - cron: '0 9 * * 1'   # every Monday at 9 am UTC
  workflow_dispatch:        # also allows manual trigger

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # required for OIDC role assumption
      contents: read

    steps:
      - name: Configure AWS credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_AUDIT_ROLE_ARN }}
          aws-region: us-east-1

      - name: Install StackSage
        run: pip install stacksage

      - name: Run audit
        env:
          STACKSAGE_LICENSE: ${{ secrets.STACKSAGE_LICENSE }}
        run: |
          stacksage audit \
            --use-cloudwatch \
            --use-cost-explorer \
            --out ./results

      - name: Upload report
        uses: actions/upload-artifact@v4
        with:
          name: stacksage-report-${{ github.run_number }}
          path: results/
          retention-days: 30

Push this file to your default branch. The audit will run automatically every Monday and can be triggered manually from the Actions tab at any time.

scan vs audit — which to use in CI?

Use stacksage audit in CI/CD pipelines — it explicitly validates the license, writes structured artifacts (HTML, JSON, CSV), and has no browser pop. Use stacksage scan for interactive runs on your laptop.

Viewing the report

After the workflow completes, go to Actions → your workflow run → Artifacts and download stacksage-report-N.zip. Open audit_report.html in your browser.

Optional: scan multiple regions

stacksage audit \
  --use-cloudwatch \
  --use-cost-explorer \
  --regions us-east-1,eu-west-1,ap-southeast-1 \
  --out ./results

Optional: use a stacksage.yml config file

Add a stacksage.yml to your repo root to set exclusions, thresholds, and required tags. StackSage picks it up automatically from the working directory. See the Configuration guide.

Related topics