Overview
Whim connects to GitHub through a dedicated Whim GitHub App that provides secure, scoped access to your repositories. The integration handles authentication, repository access, webhook-driven sync, and pull request tracking — so your AI agents can clone, branch, commit, and open PRs on your behalf.Authentication
Whim uses GitHub OAuth for user sign-in. When you first sign up or log in, you authenticate via GitHub, which grants Whim your identity and email. This is separate from the GitHub App installation, which provides repository access.Installing the Whim GitHub App
The GitHub App is installed at the team level. Once installed, all workspaces in the team can access the repositories you’ve granted.Install the GitHub App
Click Install GitHub App. You’ll be redirected to GitHub to authorize the Whim app on your personal account or organization.
Select repositories
On GitHub, choose which repositories Whim can access — either All repositories or select specific ones. You can change this at any time from your GitHub App settings.
You must be a team admin or owner to install or manage the GitHub App for a team.
Repository Permissions
The Whim GitHub App requests the following permissions:| Permission | Access | Purpose |
|---|---|---|
| Repository contents | Read & write | Clone repos, create branches, push commits |
| Pull requests | Read & write | Create and update pull requests from tasks |
| Webhooks | Read | Receive push, PR, and branch-delete events |
| Metadata | Read | List repositories and detect organization type |
Linking Repos to Workspaces
After installing the GitHub App, you can link repositories to workspaces:- Open your workspace and go to Settings > Repositories.
- Browse the list of repositories available through your team’s GitHub App installation.
- Select the repository you want to link. Whim will begin mirroring it.
Creating Repositories
Whim can also create new GitHub repositories directly from the workspace settings. New repos are created under the GitHub account or organization where the app is installed, and are private by default.Webhook Events
When you install the Whim GitHub App, GitHub automatically configures webhooks. Whim listens for the following events:Push Events
When code is pushed to a repository linked to a Whim workspace:- Whim syncs the mirror so tasks always have the latest code.
- If the push modifies files that affect workspace images (e.g.,
Dockerfile,whim.json,package.json), Whim reconciles tracked branch images to keep containers up to date.
Pull Request Events
Whim tracks pull requests on branches that follow thewhim-* naming convention (the default branch pattern for Whim tasks). Tracked actions include:
| Action | What Whim Records |
|---|---|
opened | New PR linked to a task |
reopened | PR re-opened after being closed |
closed | PR closed or merged |
ready_for_review | PR moved out of draft |
converted_to_draft | PR converted back to draft |
synchronize | New commits pushed to the PR branch |
Branch Delete Events
When a branch is deleted on GitHub, Whim automatically removes tracked branch state for that branch across any workspaces using the repository. This keeps your workspace configuration clean as branches are merged and removed.Webhook Security
All webhook payloads are verified using HMAC-SHA256 signatures (X-Hub-Signature-256 header) to ensure they originate from GitHub. Invalid or missing signatures are rejected.