Reports

LeftSize can generate reports that summarize your scan activity, fix ratio, and cost savings. Reports are generated using the same GitHub Action in stats mode.

Quick start

Add a separate workflow to generate reports on demand:

name: LeftSize Stats Report

on:
  workflow_dispatch:
    inputs:
      period:
        description: 'Stats period'
        required: false
        default: '30d'
        type: choice
        options:
          - '7d'
          - '30d'
          - '90d'
          - 'all'
      report:
        description: 'Report type'
        required: false
        default: 'summary'
        type: choice
        options:
          - 'summary'
          - 'detailed'
          - 'executive'

permissions:
  contents: read

jobs:
  stats-report:
    runs-on: ubuntu-latest
    name: Generate Stats Report
    steps:
      - name: Fetch LeftSize Stats
        id: stats
        uses: leftsize/leftsize-action@v1
        with:
          mode: stats
          installation-id: ${{ secrets.LEFTSIZE_INSTALLATION_ID }}
          repository-token: ${{ secrets.LEFTSIZE_REPOSITORY_TOKEN }}
          period: ${{ inputs.period || '30d' }}
          report: ${{ inputs.report || 'summary' }}

      - name: Display Key Metrics
        env:
          CURRENCY_SYMBOL: ${{ steps.stats.outputs.currency-symbol }}
          POTENTIAL_SAVINGS: ${{ steps.stats.outputs.potential-savings }}
          REALIZED_SAVINGS: ${{ steps.stats.outputs.realized-savings }}
          FIX_RATIO: ${{ steps.stats.outputs.fix-ratio }}
        run: |
          echo "## Key Metrics"
          echo "- Fix Ratio: ${FIX_RATIO}%"
          echo "- Potential Savings: ${CURRENCY_SYMBOL}${POTENTIAL_SAVINGS}/mo"
          echo "- Realized Savings: ${CURRENCY_SYMBOL}${REALIZED_SAVINGS}/mo"

To run the report, go to your repository’s Actions tab, select LeftSize Stats Report, and click Run workflow. The report appears in the job summary.

How it works

Stats mode fetches aggregated data from the LeftSize API for your repository. It does not scan your cloud infrastructure – it summarizes the results of previous scans.

The report is displayed in two places:

1. GitHub Actions job summary – visible on the workflow run page
2. Step outputs – individual metrics available to downstream steps

Action inputs

Set mode: stats to switch from the default scan mode to stats mode. The following inputs control the report:

Report types

Summary

A compact overview with key metrics. Good for a quick status check.

report: summary

Detailed

A full breakdown of findings by rule, category, and status. Includes per-rule savings estimates and fix rates.

report: detailed

Executive

A high-level report designed for management or stakeholders. Focuses on total savings, trends, and ROI.

report: executive

Output format

Markdown (default)

The report is rendered as a formatted markdown table in the GitHub Actions job summary. This is the best option for visual review.

format: markdown

JSON

The report is returned as structured JSON, useful for feeding into other tools, dashboards, or automation.

format: json

Action outputs

Stats mode sets the following step outputs for use in downstream steps:

Access outputs in downstream steps using ${{ steps.<step-id>.outputs.<output-name> }}.

Time periods

Examples

Scheduled weekly report

Generate a report every Monday morning:

name: Weekly LeftSize Report

on:
  schedule:
    - cron: '0 8 * * 1'

permissions:
  contents: read

jobs:
  weekly-report:
    runs-on: ubuntu-latest
    steps:
      - name: Generate Report
        id: stats
        uses: leftsize/leftsize-action@v1
        with:
          mode: stats
          installation-id: ${{ secrets.LEFTSIZE_INSTALLATION_ID }}
          repository-token: ${{ secrets.LEFTSIZE_REPOSITORY_TOKEN }}
          period: 7d
          report: summary

JSON output for automation

Fetch stats as JSON and use the values in subsequent steps:

- name: Fetch Stats
  id: stats
  uses: leftsize/leftsize-action@v1
  with:
    mode: stats
    installation-id: ${{ secrets.LEFTSIZE_INSTALLATION_ID }}
    repository-token: ${{ secrets.LEFTSIZE_REPOSITORY_TOKEN }}
    format: json

- name: Check savings threshold
  run: |
    SAVINGS="${{ steps.stats.outputs.potential-savings }}"
    echo "Potential savings: ${{ steps.stats.outputs.currency-symbol }}${SAVINGS}/mo"
    if (( $(echo "$SAVINGS > 1000" | bc -l) )); then
      echo "::warning::Potential savings exceed threshold"
    fi

Executive report for stakeholders

Generate a high-level 90-day report:

- name: Executive Report
  uses: leftsize/leftsize-action@v1
  with:
    mode: stats
    installation-id: ${{ secrets.LEFTSIZE_INSTALLATION_ID }}
    repository-token: ${{ secrets.LEFTSIZE_REPOSITORY_TOKEN }}
    period: 90d
    report: executive

Scan summaries

In addition to the stats report mode, every scan run automatically generates a summary in the GitHub Actions job summary. This summary includes:

• Findings count grouped by rule
• Estimated savings per rule
• Plan tier information (Free or Pro)
• For free-tier users: a preview of additional findings available on Pro