GitHub Permissions

Runless uses a progressive permissions model — we only ask for what you need, when you need it. This page explains what each permission level unlocks and why we request them.

Permission Levels

When you first sign in, Runless requests minimal permissions. As you use more features, we'll ask for additional access.

What You Can Do at Each Level

Identity (Default)

When you sign in for the first time, we request only identity permissions:

• ✅ Sign in with GitHub
• ✅ Add public repositories (manual sync mode)
• ✅ View workflow runs, stats, and detections
• ✅ Dismiss detections
• ❌ Cannot add private repositories
• ❌ Cannot create fix PRs

This is enough to try Runless with any public repository.

Repository Access

Grant repository access when you want to:

• ✅ Add private repositories
• ✅ View workflow file contents (for detections)
• ✅ See detection diffs
• ❌ Cannot create fix PRs (can view and copy the fix manually)

To upgrade, click Grant Access when adding a private repository, or go to Account Settings.

Workflow Access

Grant workflow access when you want Runless to create pull requests that fix detected issues:

• ✅ Everything from Repository level
• ✅ Create fix PRs that modify .github/workflows/ files
• ✅ Full automated fix workflow

Why Progressive Permissions?

Many apps request all possible permissions upfront. We don't think that's right.

Our philosophy:

1. Minimal by default — Identity only to sign in
2. Just-in-time — Request more access only when you need it
3. Transparent — Always explain what we're requesting and why
4. Revocable — You can reset permissions anytime

This means you can try Runless with zero risk — sign in with identity-only and add public repos. If you decide to go deeper, upgrade permissions as needed.

Adding Repositories

Public Repositories

You can add any public repository with just identity permissions:

1. Go to Repositories → Add Repository
2. Enter the repository (e.g., facebook/react)
3. Click Add

Runless fetches the last 30 days of workflow runs using your OAuth token.

Manual sync mode: Public repos (without the GitHub App) require manual syncing. Click the Sync button to fetch new runs.

Private Repositories

Private repositories require the Repository permission level:

1. Go to Repositories → Add Repository
2. Enter your private repository name
3. If you haven't granted repo access, you'll see a prompt to Grant Access
4. After approving, the repository is added

GitHub App vs OAuth

Runless uses two different GitHub integrations, each for a specific purpose:

Why Both?

OAuth App gives you personal access to repositories — including private repos you can access. This is how you sign in and how Runless reads/writes on your behalf.

GitHub App provides organization-wide webhook delivery. When a workflow runs in your org, GitHub sends Runless a real-time event. This is faster and more reliable than polling.

You don't need both:

• OAuth-only: Add repos manually, sync on demand
• OAuth + GitHub App: Real-time updates for installed repos

Installing the GitHub App

For real-time webhook updates:

1. Go to Team Settings → Integrations
2. Click Install GitHub App
3. Choose your organization and repositories

The GitHub App only needs read access to Actions metadata — it cannot see your code.

Creating Fix PRs

When Runless detects an issue in your workflow (like missing timeouts or unpinned actions), you can create a fix PR:

1. Click Fix this on a detection
2. Review the diff
3. Click Create Draft PR

This requires the Workflow permission level because it modifies files in .github/workflows/.

What Happens

1. Runless creates a new branch (runless-fix-{rule}-{timestamp})
2. Commits the fixed workflow file
3. Opens a draft pull request
4. You review, edit if needed, and mark ready

We always create draft PRs so you have full control before anything is merged.

If You Can't Create PRs

If the Create Draft PR button is disabled, it might be because:

Viewing Your Permissions

To see what permissions you've granted:

1. Go to Account Settings
2. Look at the GitHub Permissions section

You'll see your current level and when it was last updated.

Resetting Permissions

To downgrade or reset your GitHub permissions:

Option 1: Revoke and Re-authenticate

1. Go to GitHub Settings → Applications → Authorized OAuth Apps (opens in a new tab)
2. Find Runless and click Revoke
3. Sign in to Runless again — you'll start fresh at Identity level

Option 2: Contact Support

Email [email protected] and we can reset your stored token.

Security Considerations

Token Storage

Your GitHub OAuth token is stored encrypted in our database. We use it only to:

• Verify your identity
• Fetch workflow run data
• Create fix PRs (if you've granted workflow scope)

Scope Verification

We verify your token's scopes server-side before attempting operations:

• Adding private repos → checks for repo scope
• Creating fix PRs → checks for workflow scope

If you've revoked scopes on GitHub, Runless will prompt you to re-authenticate.

Audit Trail

All permission changes and fix PR creations are logged. You can see your activity in Account Settings.

FAQ

Why not just use the GitHub App for everything?

GitHub Apps can only access repositories where they're installed. They can't access private repos in orgs where you're a member but haven't installed the app.

OAuth tokens give you personal access to any repo you can access on GitHub — public or private, any org.

Can Runless access repos I don't have access to?

No. Your OAuth token only works for repos your GitHub account can access. If you can't see it on GitHub, Runless can't see it either.

What if I leave an organization?

If you lose access to a repository on GitHub, Runless also loses access. Your historical data remains, but no new runs will be fetched.

Is my OAuth token shared with my team?

No. Each user has their own OAuth token. When you add a private repo, it uses your token. Teammates can view the data but use their own tokens for API operations.