> ## Documentation Index
> Fetch the complete documentation index at: https://help.gowindmill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Connect GitHub to Windmill to surface pull requests, reviews, commits, and engineering contributions inside recaps, 1:1 prep, and performance reviews.

When working with engineering teams, one of the most important activities is committing code to repositories. Windmill's GitHub integration helps surface the work happening in your codebase by understanding how code changes, who's contributing, and how teams collaborate.

## Why connect GitHub

Connecting GitHub to Windmill brings your engineering work directly into performance conversations—without needing to self-promote or write summaries.

* Your contributions are captured as they happen (commits, PRs, code reviews)
* Surfaces patterns in collaboration, code ownership, and problem-solving
* Helps managers coach using actual context from your work
* Ensures reviews recognize both shipped code and behind-the-scenes contributions like code review

Windmill turns GitHub activity into fair, accurate insight for 1:1s, feedback, and performance reviews.

## What Windmill accesses

**Windmill stores git diffs—including the actual code changes.** We analyze file diffs in PRs to understand the work you're contributing, contextualize PR comments and code reviews, and surface collaboration patterns. While those diffs could theoretically be used to reconstruct your codebase, we don't store complete source files or attempt to reassemble your code. We focus on understanding how your code evolves and how teams collaborate.

### Code changes and commits

Windmill reads commit metadata and diffs to understand:

* **Who is making changes** – Attribution based on git author configuration
* **What changed** – The scope and nature of contributions (lines added/removed, files modified)
* **Collaboration patterns** – Who's working on the same code or projects

We store the actual code changes in diffs to analyze your contributions and provide context for code reviews. While this gives us access to your code, we don't maintain complete source files—we care about how your codebase evolves, not the final state.

### Pull requests and code reviews

Pull requests are a key signal for understanding engineering work and collaboration. Windmill tracks:

* **Who opened, merged, or contributed to PRs**
* **Code review activity** – Who's reviewing, approving, and commenting on code
* **Review cycle time** – How long PRs spend in review
* **Collaboration and feedback** – The back-and-forth between engineers during code review

Code review is often a strong signal of performance—whether you're doing thorough reviews or submitting PRs that require less iteration.

### Issues and project work

Windmill reads issue metadata to show:

* Issues created, owned, or completed
* Follow-through on project contributions
* Attribution to the right individuals and teams

## How Windmill uses GitHub data

When connected, Windmill securely reads the following activity signals from GitHub:

| Data Type                                | How Windmill Uses It                                                                           |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Pull requests (opened, merged, reviewed) | Surfaces in Recaps, 1:1s, and performance reviews to highlight shipped work and ownership      |
| Code review comments and approvals       | Shows collaboration, mentoring, and teamwork; appears in stats and organizational insights     |
| Issues created, owned, or completed      | Tracks project contributions and follow-through                                                |
| Commit metadata and diffs                | Analyzes actual code changes to understand contribution patterns and contextualize PR activity |
| Repository and project associations      | Maps work to the right individuals and teams                                                   |

## Permissions

Windmill requests **read-only** access through GitHub's standard OAuth flow.

| Permission                                    | Purpose                                                    |
| --------------------------------------------- | ---------------------------------------------------------- |
| `repo:read` (or scoped metadata access)       | Read PRs, issues, commits, and diffs                       |
| Read collaborator/contributor metadata        | Map contributions to individuals in Windmill               |
| **No write access**                           | Windmill never modifies repos, pushes commits, or comments |
| **Scoped to selected repos or organizations** | You choose what's included—you can change this anytime     |

You need to be a GitHub Owner or Manager to connect the integration.

## Attribution

Windmill attributes work based on git author configuration and GitHub activity.

### Commits

Commits are attributed based on the **git author** configured locally (not your GitHub username). To ensure correct attribution, set your git config:

```bash theme={null}
git config user.name "John Doe"
git config user.email "john.doe@example.com"
```

Use your work email to ensure commits are mapped to your Windmill profile.

### Coding agents

If you use coding agents, attribution depends on how the agent commits code:

**Attributed to a bot user:**

* Devin
* Claude Code (via GitHub Actions)

**Attributed to you (the requesting user):**

* OpenAI Codex
* Cursor
* Claude Code (locally)

<Tip>
  If you notice incorrect attribution in your Recaps or stats, check your git
  configuration and coding agent settings.
</Tip>

## Username mapping

GitHub usernames don't always match work email addresses, which can cause attribution issues. If your GitHub activity isn't showing up—or is attributed to the wrong person—an admin can fix this.

Admins can map GitHub usernames to employees at [Settings > Integrations > Mapping](https://app.gowindmill.com/COMPANY/config/mappings). You'll see both GitHub usernames and local machine names used in commits.

To check for unmapped users, go to **External Users** and filter by GitHub.

## FAQs

<AccordionGroup>
  <Accordion title="Why does Windmill need access to the actual code?">
    Windmill stores **git diffs**, which include the actual code you wrote—the
    lines added, removed, and modified. We analyze file diffs to understand the
    work you're contributing, contextualize PR comments and code reviews, and
    measure impact. While diffs could theoretically reconstruct your codebase,
    we don't store complete source files or attempt to reassemble your code. We
    focus on understanding how your codebase evolves over time.
  </Accordion>

  <Accordion title="Does Windmill store my code?">
    Windmill stores git diffs, which include the actual code changes you
    make—not just metadata. We analyze these diffs to understand **who
    contributed what**, **how code evolves**, and **how teams collaborate**.
    While diffs could theoretically be used to reconstruct your codebase, we
    don't store complete source files or attempt to reassemble your code.
  </Accordion>

  <Accordion title="Do I have to connect GitHub?">
    No. GitHub is a very powerful integration for engineers—it surfaces
    contributions, code reviews, and collaboration patterns that help in
    performance conversations. However, you don't have to connect GitHub to use
    Windmill. The platform works with or without it.
  </Accordion>

  <Accordion title="Do we need to sync our entire GitHub org?">
    No. You choose which repos or teams to sync. You can change or revoke access
    at any time from your GitHub settings.
  </Accordion>

  <Accordion title="Does Windmill write anything back to GitHub?">
    No. The integration is strictly read-only. Windmill never pushes commits,
    modifies repos, or comments on PRs.
  </Accordion>

  <Accordion title="How often is data synced?">
    Continuously. Activity appears in Windmill shortly after it happens in
    GitHub—usually within minutes.
  </Accordion>

  <Accordion title="Is this integration secure?">
    Yes. All data is encrypted in transit and at rest. Windmill maintains SOC 2
    compliance and uses scoped OAuth tokens. You control which repos are synced.
  </Accordion>

  <Accordion title="What happens if an engineer leaves?">
    Their historical contributions remain visible for context, but Windmill
    stops associating new activity once they're marked as an Archived user.
  </Accordion>

  <Accordion title="Why aren't my GitHub activities showing up?">
    This usually happens when your GitHub username doesn't match your work
    email. Check the **Settings > Integrations > GitHub > Mapping** tab to map
    your GitHub username to your employee profile. Admins can fix this at
    [Settings > Integrations >
    Mapping](https://app.gowindmill.com/COMPANY/config/mappings).
  </Accordion>

  <Accordion title="Why do I need to sign my commits?">
    Signing commits proves you created them and keeps your work secure. For
    Windmill, signing commits ensures your contributions are properly attributed
    to you in stats, recaps, and performance reviews.
  </Accordion>

  <Accordion title="Do you support other code repositories like GitLab?">
    Currently, Windmill only supports GitHub. We're planning to add GitLab and
    other repositories in the future.
  </Accordion>
</AccordionGroup>