Teams

CodePeel supports shared GitHub App installations so multiple developers can collaborate on the same repositories. Each team member sees shared repos on their own dashboard, receives reviews on the PRs they author, and is billed independently from their own plan quota. There is no separate "team plan" to purchase — teams are formed organically when multiple CodePeel users connect to the same GitHub organization or account.

---

Overview

When you install the CodePeel GitHub App on a GitHub organization or personal account, you become the owner of that installation. Other developers who sign up for CodePeel and connect to the same GitHub account are automatically added as members. Both owners and members see the same repositories on their dashboards, but each person is only charged for the pull requests they personally open.

This model mirrors how teams naturally work on GitHub: one person installs the integration for the organization, and everyone on the team benefits from automated reviews on their pull requests. CodePeel recognizes each team member by their GitHub identity and routes billing, notifications, and review records to the correct person.

The teams feature requires no configuration, no invitations to send, and no admin portal to manage. Members self-serve by connecting to a GitHub account that already has CodePeel installed. The system handles the rest.

---

Roles

CodePeel defines two roles within a shared installation. Roles are determined automatically based on who connected to the installation first.

Owner

The owner is the CodePeel user who first installed the GitHub App on a given GitHub organization or personal account. There is exactly one owner per installation. The owner has full control over the installation: they can disconnect or reconnect individual repositories, remove members from the team, and manage repository-level settings like .codepeel.yml configuration.

The owner also serves as the billing fallback. When an external contributor without a CodePeel account opens a pull request on a connected repository, the review is charged to the owner's quota since no other CodePeel user can be matched to the PR author.

Member

A member is any CodePeel user who joins an existing installation after the owner has set it up. Members see the same repositories on their dashboard and receive reviews on the PRs they author, charged against their own individual plan. Members cannot disconnect repositories, remove other members, or modify installation-level settings.

Members can leave an installation at any time. Leaving removes the shared repositories from their dashboard but preserves all historical review data associated with their account.

---

Setting Up a Team

There are two ways to add members to a team. The owner can add them directly from the CodePeel dashboard (recommended and most reliable), or members can self-serve by connecting to the same GitHub account. No invitation codes or email invites are required.

Method 1: Owner adds members from the dashboard (recommended)

This is the most reliable way to build a team because it does not depend on GitHub's redirect behavior. The owner adds members directly by their GitHub username or email.

1. The team member signs up for CodePeel at codepeel.com (any plan, including Free)
2. The owner goes to the Repositories page and opens the Team panel
3. The owner clicks Add member
4. The owner enters the member's GitHub username (e.g., bobsmith) or the email they signed up with
5. CodePeel finds their account and adds them to the installation immediately

The member's dashboard then shows the shared repositories the next time they load the page. The member must already have a CodePeel account before they can be added — if no account is found, CodePeel returns an error asking them to sign up first.

Method 2: Member joins from their own dashboard

Members can join an existing team without any action from the owner. This is available from the onboarding checklist (for new accounts) and from the Repositories page (for all users).

1. The team member signs up for CodePeel
2. They navigate to Repositories and click Join a team (in the header or the empty state)
3. They enter the GitHub username of the installation owner (e.g., hexivine)
4. CodePeel finds the installation associated with that username and adds the member immediately
5. The shared repositories appear on their dashboard

This path also appears in the onboarding checklist when a new user has no connected repos. Step 1 shows both "Install App" and "Join a team" as options.

The member does not need to be invited or approved by the owner — entering the owner's username is enough. If no installation is found for the given username, CodePeel shows an error explaining that the owner needs to install the app first.

Method 3: Member self-joins via GitHub (new installations only)

When a member connects to a GitHub account where CodePeel is being installed for the first time, GitHub redirects them back to CodePeel and they are added automatically.

1. The team member signs up for CodePeel
2. They navigate to Repositories and click Connect
3. On GitHub's authorization screen, they select the organization
4. If this creates a new installation, GitHub redirects back to CodePeel and links them

Important limitation: GitHub only redirects back to CodePeel when a new installation is created. If the CodePeel app is already installed on the account (the common case for an existing team), GitHub shows its configuration page and does not redirect. In that situation, the member should use Method 2 (Join a team) or the owner should use Method 1 to add them.

The owner installs the GitHub App first

Regardless of which method you use to add members, one person must first install the CodePeel GitHub App on the organization. That person becomes the owner.

1. Sign in to CodePeel at codepeel.com/app
2. Navigate to Repositories and click Connect
3. Authorize the CodePeel app on GitHub
4. Select the GitHub organization or personal account to connect
5. Choose which repositories to grant access to
6. Click Install to complete the setup

After installation, the connected repositories appear on the owner's dashboard within seconds, and the owner can begin adding members.

---

How Billing Works for Teams

CodePeel uses author-based billing for shared installations. Each developer's pull request reviews are charged to their own CodePeel plan, regardless of who owns the installation. This ensures no single person subsidizes their teammates' usage.

Billing resolution order

When a pull request is opened on a repository connected to a shared installation, CodePeel determines who to bill using the following resolution order:

1. Match by GitHub numeric ID: The system looks up the PR author's stable GitHub user ID against all CodePeel user records. This ID never changes, even if the author renames their GitHub account.
2. Match by GitHub login: If no match is found by ID (for users who have not logged in since the feature was introduced), the system tries a case-insensitive match on the author's GitHub username.
3. Verify installation access: If a matching CodePeel user is found, the system confirms they are the owner or a member of this specific installation before billing them.
4. Fallback to owner: If no matching CodePeel user is found (e.g., an external contractor, a bot, or a contributor who has not signed up), the installation owner is charged.

Billing examples

Consider a team of three developers sharing an installation on the acme-corp GitHub organization:

Each person's review count increments independently. Bob using 10 reviews does not affect Alice's or Charlie's remaining quota. The only scenario where the owner absorbs cost is when the PR author has no CodePeel account at all.

What counts as a review

The billing rules for teams are identical to individual usage. Each PR review consumes 1 to 5 reviews from the billed user's quota depending on the diff size. IDE reviews, MCP tool calls, and chat interactions also draw from the same pool. See the Billing documentation for the full deduction table.

---

Managing Members

The Repositories page includes a Team panel that shows all members of each installation along with their usage statistics. Access controls differ based on your role.

Viewing the team

Navigate to the Repositories page in your dashboard. The Team panel appears below the repository list. If you have access to multiple installations, a dropdown lets you switch between them. Each member row shows:

• Their display name and GitHub username
• Their role (Owner or Member)
• Their plan tier (Free, Pro, or Max)
• Reviews consumed this billing period

Adding a member (owner only)

As the installation owner, click Add member in the Team panel. Enter the member's GitHub username or the email address they used to sign up. CodePeel looks up their account and adds them to the installation. The member must already have a CodePeel account — if none is found, you will see an error asking them to sign up first.

When matching by username, CodePeel uses a case-insensitive match and strips a leading @ if present (so both bobsmith and @bobsmith work). When matching by email, it uses the exact email stored on the account.

Removing a member (owner only)

As the installation owner, you can remove any member from the team. Removing a member:

• Immediately removes the shared repositories from their dashboard
• Does not delete their past reviews or account data
• Does not affect their CodePeel subscription
• They can rejoin later by going through the "Connect" flow again

To remove a member, click the remove icon next to their name in the Team panel and confirm the action in the dialog.

Leaving an installation (member only)

If you are a member and want to disconnect from a shared installation:

• Click the leave icon next to your own name in the Team panel
• Confirm the action in the dialog
• The shared repositories disappear from your dashboard immediately
• Your past reviews and account remain intact
• You can rejoin at any time by clicking "Connect" again

Transferring ownership

Ownership transfer is not currently supported through the dashboard. To transfer ownership of an installation:

1. The current owner uninstalls the GitHub App from GitHub's settings page (Settings > Integrations > Applications > CodePeel > Uninstall)
2. The new owner installs the GitHub App on the same organization
3. Previous members rejoin by clicking "Connect" and selecting the organization

All historical review data is preserved in each user's individual account regardless of installation ownership changes.

---

How It Works

The teams feature is built on top of CodePeel's GitHub App installation system. Understanding the underlying flow helps explain the behavior in edge cases.

Installation document structure

Each GitHub App installation is represented by a Firestore document in the installations collection. The document ID is the GitHub installation's numeric ID (assigned by GitHub). Key fields include:

User identity fields

Each CodePeel user document stores two fields used for PR author matching:

These fields are populated automatically when a user signs in. The githubId is extracted server-side from Firebase Auth's provider data (no client cooperation needed). The githubLogin is fetched from the GitHub API during the OAuth sign-in flow and sent to the server for storage.

For existing users who signed up before the teams feature was introduced, these fields are backfilled on their next login. A one-time migration script can also be run to populate githubId for all users immediately using Firebase Auth's listUsers API.

Join flow (setup page)

When a user completes the GitHub App installation or configuration flow, GitHub redirects them to CodePeel's setup page with an installation_id query parameter. The setup page performs the following logic:

1. Reads the installation document from Firestore
2. If the document has no uid field (new installation): sets the current user as owner and adds them to the members array
3. If the document already has a uid that differs from the current user (existing installation owned by someone else): adds the current user to the members array without overwriting the owner
4. If the document's uid matches the current user: no changes needed (reconnecting)

This logic ensures that the first user to connect becomes the owner, and subsequent users join as members without disrupting the existing setup.

Dashboard data flow

The Repositories page uses two real-time Firestore listeners to build the complete list of accessible installations:

• Query 1: installations where uid == currentUser (owned installations)
• Query 2: installations where members array-contains currentUser (member installations)

Results from both queries are merged client-side. Each installation is tagged with the user's role (owner or member) based on whether the uid field matches. The merged list drives both the repository display and the Team panel.

PR billing flow

When a pull request event arrives via GitHub webhook, the billing resolution function (resolveBillingUid) executes:

1. Reads the installation document to get uid (owner) and members array
2. Extracts the PR author's GitHub numeric ID and login from the webhook payload
3. Queries the users collection for a matching githubId, then falls back to githubLogin
4. If a match is found AND that user is in the members array or is the owner: bills that user
5. Otherwise: bills the owner as fallback

The review record is stored in the billed user's subcollection (users/{uid}/reviews/{reviewId}), ensuring it appears on their dashboard and contributes to their usage statistics.

---

API Reference

The following endpoints support team management operations. All endpoints require a valid Firebase ID token in the Authorization header.

List members

GET /api/github/installations/{installationId}/members
Authorization: Bearer <token>

Returns the complete list of users with access to an installation. Only accessible by the owner or an existing member.

Response:

{
  "members": [
    {
      "uid": "abc123",
      "displayName": "Alice Chen",
      "githubLogin": "alicechen",
      "photoURL": "https://avatars.githubusercontent.com/u/12345",
      "tier": "max",
      "reviewsUsedThisPeriod": 47,
      "role": "owner"
    },
    {
      "uid": "def456",
      "displayName": "Bob Smith",
      "githubLogin": "bobsmith",
      "photoURL": null,
      "tier": "pro",
      "reviewsUsedThisPeriod": 12,
      "role": "member"
    }
  ],
  "ownerUid": "abc123",
  "isOwner": true
}

Join an installation

POST /api/github/installations/join
Authorization: Bearer <token>
Content-Type: application/json

{ "ownerLogin": "hexivine" }

Allows a user to join an existing installation by specifying the owner's GitHub username. The system looks up the installation by accountLogin or by the owner's githubLogin field, then adds the caller to the members array. No approval from the owner is required.

Returns { "success": true } on success, or { "success": true, "alreadyMember": true } if the user is already a member. Returns 404 if no installation is found for the given username.

Add a member

POST /api/github/installations/{installationId}/members
Authorization: Bearer <token>
Content-Type: application/json

{ "githubLogin": "bobsmith" }

Adds a member to the installation by GitHub username or email. Only the owner can call this endpoint. The body accepts either githubLogin or email. The target must already have a CodePeel account. Returns the added member's basic info on success:

{
  "success": true,
  "member": {
    "uid": "def456",
    "displayName": "Bob Smith",
    "githubLogin": "bobsmith"
  }
}

Possible error responses: 400 if no username/email is provided or the user is already a member, 403 if the caller is not the owner, 404 if no CodePeel account matches the username or email.

Remove a member

DELETE /api/github/installations/{installationId}/members
Authorization: Bearer <token>
Content-Type: application/json

{ "memberUid": "def456" }

Removes a member from the installation. Only the owner can call this endpoint. The owner cannot remove themselves. Returns { "success": true } on success.

Leave an installation

POST /api/github/installations/{installationId}/leave
Authorization: Bearer <token>

The calling user removes themselves from the installation's member list. The owner cannot use this endpoint (returns a 400 error with instructions to uninstall on GitHub instead). Returns { "success": true } on success.

---

Troubleshooting

I connected to GitHub but was not added as a member

GitHub only redirects back to CodePeel when a brand-new installation is created. If the CodePeel app is already installed on the organization (the common case when joining an existing team), GitHub shows its own configuration page and does not send you back to CodePeel — so you are not added automatically.

The fix: use the Join a team button on the Repositories page (or in the onboarding checklist). Enter the owner's GitHub username and you will be added instantly. Alternatively, the owner can add you from their Team panel.

I connected but do not see any repositories

This typically means you selected a different GitHub account than the one where CodePeel is installed, or you joined an installation that already existed (see the issue above). If you are joining an existing team, have the owner add you from their dashboard. If you intended to connect your own separate organization, click "Connect" again and ensure you select the correct account.

I see "Member" on repos but reviews are not showing on my dashboard

Reviews appear on the dashboard of the user who is billed for them. CodePeel attributes reviews based on the GitHub account that authored the pull request — not the CodePeel account you are signed into.

A common mistake: you are signed into CodePeel as "ForinitTech" (a member), but you open the PR on GitHub while logged into a different GitHub account (e.g., the owner's account "hexivine"). Since the PR author on GitHub is "hexivine", CodePeel bills hexivine and stores the review under their account. Your dashboard shows nothing.

To fix this:

1. Make sure you are logged into GitHub with the same account that matches your CodePeel identity. Check which GitHub username appears in the Team panel next to your name — that is the account you must use to author PRs.
2. Open the pull request from that GitHub account. CodePeel matches the PR author's GitHub ID to your CodePeel user record.
3. If you have multiple GitHub accounts, always create PRs from the one linked to your CodePeel account.

If your githubLogin or githubId fields are missing (common for accounts created before the teams feature), simply sign out and sign back in. The system backfills these fields automatically on login.

The owner changed their GitHub username

Author matching uses the stable GitHub numeric user ID as the primary identifier. GitHub username changes do not affect billing attribution. The githubLogin field is used only as a fallback for users whose githubId has not yet been populated.

I want to add repos from a different GitHub account

Each GitHub account or organization requires its own separate installation of the CodePeel GitHub App. If you want CodePeel to review repos across multiple organizations, install the app on each one. You can be an owner or member of multiple installations simultaneously — they all appear on your dashboard.

A team member left but their past reviews are still visible

This is expected behavior. Leaving an installation only removes future repo visibility from that member's dashboard. All review records created while they were a member remain in their account permanently. Review history is never deleted when membership changes.

---

Frequently Asked Questions

Do members need a paid plan to join a team?

No. Members can join on the Free tier (30 reviews per month). They will be limited by their own plan's quota and rate limits, but they can still see repositories and receive reviews. The owner's plan does not extend to members, and members do not inherit Pro or Max features from the owner.

Can one person be a member of multiple installations?

Yes. If you contribute to repositories across multiple GitHub organizations, and each organization has CodePeel installed, you will see all of them on your Repositories page. Your reviews across all installations draw from a single shared monthly quota on your own plan.

What happens if a member exhausts their quota?

When a member's monthly review quota is exhausted, their pull requests are not reviewed until the quota resets on the 1st of the next month (or they upgrade their plan). Other team members are unaffected — the owner's quota is not used as a secondary pool for members who run out. The member receives a comment on their PR indicating their quota is exhausted.

Can the owner see members' review content?

No. Each user's reviews are stored privately in their own account. The Team panel shows aggregate usage statistics (reviews consumed this period) but does not expose the content of individual reviews, findings, or PR details belonging to other members.

I opened a PR but the review went to the owner instead of me

This happens when the GitHub account you used to create the pull request does not match your CodePeel identity. CodePeel bills the person whose GitHub account authored the PR — not the CodePeel account viewing the dashboard.

For example: if your CodePeel account is linked to the GitHub user "ForinitTech", but you created the PR while logged into GitHub as "hexivine" (the owner), the review is attributed to hexivine. Always open PRs from the GitHub account shown next to your name in the Team panel.

Is there a limit on how many members can join an installation?

There is no enforced limit on the number of members per installation. Any CodePeel user who has access to the GitHub organization (and goes through the "Connect" flow) can join as a member.

How does this compare to competitors like CodeRabbit?

CodeRabbit uses per-seat organization billing where the organization pays a fixed per-user monthly fee. CodePeel takes a different approach: each developer subscribes individually and is charged only for the PRs they author. This means teams can form without requiring a central billing admin or an explicit "create team" step. The trade-off is that each member manages their own subscription independently.

---

Related Documentation

• Getting Started — Install CodePeel and run your first review
• Billing — Plans, pricing, quota mechanics, and the team billing summary
• Configuration — Repository-level .codepeel.yml settings (owner-managed)
• FAQ — General troubleshooting and common questions