Skip to content

GitHub PR Setup

To use --github output mode, you need to configure GitHub access.

1. Create a GitHub Token

  1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
  2. Create a token with:
  3. Repository access: Select the repo where you want PRs opened
  4. Permissions: Contents: Read and write, Pull requests: Read and write

Or use a classic token with repo scope.

2. Configure the Token

iam-zero configure

Enter your token when prompted.

Edit ~/.iam-zero/config.toml:

[github]
token = "ghp_your_token_here"
repo = "your-org/your-infra"

3. Scan with PR Output

iam-zero scan aws --role arn:aws:iam::123456789012:role/my-role --github

How PRs Work

When --github is used, iam-zero:

  1. Creates a new branch in the configured repo
  2. Commits the recommended policy as iam-zero/aws/my-role.recommended-policy.json
  3. Opens a PR with the full before/after diff
  4. Sets the PR title to fix(iam): tighten permissions for my-role [aws]

Idempotency

iam-zero checks if a PR already exists for this identity before opening a new one. Running the same scan twice won't create duplicate PRs.

PR Contents

Each PR includes:

  • Summary — N unused permissions, M recommended for removal
  • Findings table — Permission | Last Used | Recommendation | Risk
  • Policy diff — full before/after in code blocks
  • Testing instructions