How It Works

LeftSize integrates with GitHub Actions and your cloud provider to deliver infrastructure optimization recommendations as GitHub Issues.

Architecture overview

Your Repository          LeftSize Action           LeftSize API
┌──────────────┐        ┌──────────────┐        ┌──────────────┐
│ .github/     │        │ Cloud        │        │ Template     │
│ workflows/   │───────>│ Custodian    │───────>│ Engine       │
│ leftsize.yml │  runs  │ Policies     │ submit │              │
└──────────────┘        └──────────────┘ findings└──────┬───────┘
                                                       │
                                                       │ creates
                                                       v
                                                ┌──────────────┐
                                                │ GitHub       │
                                                │ Issues       │
                                                └──────────────┘

The scan cycle

1. Scheduled trigger

A GitHub Actions workflow runs on a daily cron schedule (randomized per repository to distribute load). You can also trigger scans manually from the Actions tab.

2. Cloud authentication

The workflow authenticates to your cloud provider using OIDC – no stored credentials. GitHub Actions requests a short-lived token that’s valid only for the duration of the scan.

3. Policy execution

The LeftSize Action runs Cloud Custodian policies against your infrastructure. These policies check for:

• Cost optimization – idle resources, oversized instances, missing discounts
• Security – unencrypted storage, public access, open network ports
• Governance – missing ownership tags, compliance gaps
• Deprecations – outdated service versions, upcoming retirements

Policies are read-only. They query resource metadata and CloudWatch/Azure Monitor metrics but never modify anything.

4. Findings submission

Detected findings are submitted to the LeftSize API along with your installation ID and repository token. The API groups findings by rule and scope (e.g., all idle VMs in a subscription).

5. Issue creation

The template engine renders a GitHub Issue for each group of findings using Handlebars templates. Each issue includes:

• A title with the category prefix (e.g., [COST], [SECURITY], [DEPRECATION])
• A list of affected resources with relevant details
• Estimated monthly savings (for cost optimization findings)
• Available @leftsize commands for interactive guidance

6. Issue lifecycle

Issues are managed over time:

• New findings create new issues
• Recurring findings update existing issues and add recurrence labels
• Resolved findings (resources cleaned up) are not re-opened
• Snoozed issues are suppressed until the snooze period expires

What runs where

Your cloud credentials never leave your GitHub Actions runner. The LeftSize API only receives finding metadata (resource names, types, regions) – not credentials or sensitive data.

Detection methods

LeftSize uses several detection strategies:

Metrics-based detection

For resources like VMs, databases, and Lambda functions, LeftSize queries CloudWatch or Azure Monitor metrics over a time window (typically 14-30 days). A resource is flagged as idle when key metrics are consistently at or near zero.

Configuration-based detection

For resources like unattached disks, unused IP addresses, and missing encryption, LeftSize checks resource configuration directly. These checks don’t require metrics data.

Age-based filtering

To avoid false positives on newly created resources, most policies include an age filter. A resource must exist for a minimum period (typically 14-30 days) before it’s flagged.

Cost estimation

Where possible, LeftSize estimates monthly savings based on the resource type, size, and pricing tier. These estimates use public pricing data and may not reflect negotiated discounts or reserved instance pricing.

Reports and statistics

In addition to scanning, the LeftSize Action supports a stats mode that generates reports summarizing your scan activity, fix ratio, and cost savings over time. Reports are available in three types (summary, detailed, executive) and can be generated on demand or on a schedule.

Stats mode does not scan your cloud infrastructure – it fetches aggregated data from the LeftSize API. See the Reports guide for setup instructions and examples.

Plans and limits

See the rules catalog for which rules are included in each plan.