Installation
Runless connects to GitHub via a GitHub App. This page explains the installation process and what permissions are required.
Installing the GitHub App
For Organizations
- Go to Settings in Runless (or click the prompt on your dashboard)
- Click Install GitHub App
- Select your organization
- Choose which repositories to include:
- All repositories - Recommended for full visibility
- Select repositories - Choose specific repos
For Personal Accounts
The process is the same, but you'll select your personal account instead of an organization.
Required Permissions
The app will request these permissions:
| Permission | Level | Why We Need It |
|---|---|---|
| Actions | Read | Receive webhook events for workflow runs |
| Metadata | Read | List repositories and their workflows |
We never request write access to your code, issues, pull requests, or any other repository content.
Webhook Events
Runless subscribes to these webhook events:
workflow_run- Triggered when a workflow run is requested, in progress, or completedworkflow_job- Triggered for each job within a workflow run
Adding More Repositories Later
You can modify which repositories Runless has access to at any time:
- Go to Settings in Runless
- Click Manage GitHub App
- Add or remove repositories as needed
Changes take effect immediately — new runs will appear within seconds.
Uninstalling
To remove Runless from your repositories:
- Go to your GitHub organization/account settings
- Navigate to Installed GitHub Apps
- Find Runless and click Configure
- Click Uninstall
Your historical data in Runless will be preserved but marked as inactive. You can reinstall later and it will resume tracking.
Adding Repositories Manually
You can add repositories without installing the GitHub App. This works for both public and private repos.
Adding a Repository
- Go to Repositories in Runless
- Click Add Repository
- Enter the repository name (e.g.,
facebook/reactoryour-org/private-repo) - Click Add
Runless will fetch the last 30 days of workflow runs and display them on your dashboard.
Public vs Private Repositories
| Repository Type | Required Permission | How to Grant |
|---|---|---|
| Public | Identity (default) | Automatic on sign-in |
| Private | Repository access | Click "Grant Access" when prompted |
For private repos, you need the Repository permission level. Runless will prompt you to grant access if needed. See GitHub Permissions for details.
How Manual Sync Works
Manually-added repos operate in manual sync mode:
| Feature | App-Installed Repos | Manual Repos |
|---|---|---|
| Real-time updates | ✅ Webhooks | ❌ Manual refresh |
| Historical import | ✅ Automatic | ✅ Automatic |
| Sync new runs | ✅ Automatic | 🔄 Click "Sync" |
| API access | GitHub App token | Your OAuth token |
Manual repos show a "Manual Sync" badge and a "Sync Now" button to fetch the latest runs.
Limitations
- No real-time webhook updates (you need to manually sync)
- Rate limited by your personal GitHub API quota
- You can only add repos your GitHub account has access to