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

# GitHub

> Connect GitHub repositories, issues, pull requests, and projects

The GitHub integration is Kasava's most comprehensive integration, enabling repository indexing, issue management, commit analysis, and Projects V2 sync. GitHub serves as the foundation for Kasava's code intelligence features.

## Capabilities

| Feature             | Description                                         |
| ------------------- | --------------------------------------------------- |
| Repository Indexing | Index code for semantic search and AI chat          |
| Issues & PRs        | Sync issues and pull requests to Products           |
| Projects V2         | Sync GitHub Projects boards with Kanban view        |
| Commits             | AI-powered semantic analysis of commit history      |
| Webhooks            | Real-time updates on changes                        |
| Code Intelligence   | AST parsing, symbol extraction, and semantic search |

## Connecting GitHub

GitHub connection is handled through the GitHub App installation flow, which differs from other OAuth-based integrations.

<Steps>
  <Step title="Navigate to Integrations">
    Go to **Settings > Integrations** in the sidebar
  </Step>

  <Step title="Find GitHub Issues">
    In the **Task Management** section, locate the GitHub Issues integration card
  </Step>

  <Step title="Click Connect">
    Click the green **Connect** button to begin the GitHub App installation
  </Step>

  <Step title="Select Account">
    Choose whether to install for your personal account or an organization you administer
  </Step>

  <Step title="Choose Repositories">
    Select **All repositories** or **Only select repositories** to control access
  </Step>

  <Step title="Complete Installation">
    Click **Install** to finish. You'll be redirected back to Kasava.
  </Step>
</Steps>

## Repository Access Options

When installing the GitHub App, you can choose your access level:

### All Repositories

Grants Kasava access to all current and future repositories in your account or organization. Best for:

* Full organization adoption
* Automatic access to new repositories
* Simplified management

### Select Repositories

Choose specific repositories for Kasava to access. Best for:

* Trying Kasava with a few repositories first
* Restricting access to specific projects
* Compliance requirements

<Note>
  You can update repository access anytime in GitHub Settings > Applications > Kasava.
</Note>

## Multiple GitHub Installations

Kasava supports connecting multiple GitHub App installations, allowing you to access repositories from different GitHub accounts or organizations within a single Kasava organization.

### Adding Additional Installations

<Steps>
  <Step title="Go to Settings > Integrations">
    Navigate to the integrations settings page
  </Step>

  <Step title="Click Add Installation">
    If GitHub is already connected, click **Add GitHub Installation** to connect another account
  </Step>

  <Step title="Select New Account">
    Choose a different GitHub account or organization to install
  </Step>

  <Step title="Grant Access">
    Select repositories and complete the installation
  </Step>
</Steps>

<Tip>
  Multi-installation support is useful for agencies managing multiple clients, or organizations with separate GitHub accounts for different projects.
</Tip>

## Managing Repositories

Once the GitHub App is connected, manage your repositories from **Settings > Repositories**.

### Repository List

The Repositories page displays a split-view interface:

* **Left panel** - List of all connected repositories with search and filter
* **Right panel** - Quick overview of the selected repository showing sync status, default branch, and indexing status

### Adding Repositories from GitHub App

Click **Manage Repositories** to import repositories that the GitHub App has access to:

<Steps>
  <Step title="Open Manage Repositories">
    From **Settings > Repositories**, click the **Manage Repositories** button
  </Step>

  <Step title="Select Repositories">
    Check the repositories you want to import. Repositories are sorted by creation date with newest first.
  </Step>

  <Step title="Apply Changes">
    Click **Apply Changes** to import the selected repositories. You can import multiple repositories at once.
  </Step>
</Steps>

<Note>
  Only repositories that the GitHub App has access to will appear in the list. To add more repositories, click **Update GitHub Settings** to modify access in GitHub Settings > Applications > Kasava.
</Note>

### Importing Public Repositories

Import any public GitHub repository without needing GitHub App access - useful for exploring open source projects:

<Steps>
  <Step title="Click Import Public Repo">
    From **Settings > Repositories**, click the **Import Public Repo** button
  </Step>

  <Step title="Enter Repository Details">
    Enter the repository in one of these formats:

    * Full URL: `https://github.com/facebook/react`
    * Owner/repo format: `facebook/react`
  </Step>

  <Step title="Configure Options">
    * **Branch** (optional) - Specify a branch or leave empty to use the default branch
    * **Start indexing immediately** - Enable to begin code indexing right after import
  </Step>

  <Step title="Import">
    Click **Import Repository** to add the public repository
  </Step>
</Steps>

<Info>
  Public repositories sync manually without real-time webhook updates. Use the **Sync** button on the repository overview to pull the latest changes whenever needed.
</Info>

### Removing Repositories

To remove a repository from Kasava:

1. Click **Manage Repositories**
2. Uncheck the repository you want to remove
3. Click **Apply Changes**
4. Confirm the removal when prompted

## Repository Detail Page

Click **View Details** on any repository from the overview panel to access the full repository page with detailed information and management options.

### Overview Tab

The Overview tab displays key repository information:

| Information    | Description                                           |
| -------------- | ----------------------------------------------------- |
| Default Branch | The primary branch for the repository                 |
| Last Sync      | When data was last synchronized from GitHub           |
| Index Status   | Current indexing progress and number of files indexed |
| Description    | Repository description from GitHub                    |

### Documents Tab

View and configure auto-generated documentation:

* Browse generated documentation files
* Configure documentation generation settings
* Set up triggers and filters for automatic updates

### Insights Tab

AI-generated insights about your codebase:

* Code quality observations
* Architecture recommendations
* Trends and patterns detected

### Activity Tab

View commits and pull requests with AI-powered analysis:

* **Commit Type Detection** - Automatic categorization (feat, fix, refactor, etc.)
* **Impact Assessment** - High, Medium, or Low impact rating
* **Business Value** - AI-assessed business impact
* Filter by date range, authors, or commit type

### Logs Tab

View synchronization and system logs:

* Sync events and their status
* Indexing progress
* Any errors that occurred

### Settings Tab

Configure repository-specific settings:

* Enable or disable code indexing
* Manage sync preferences
* Configure branch settings

## Code Indexing

Index repositories to enable powerful AI features:

* **Semantic Code Search** - Search code by meaning, not just keywords
* **AI Chat** - Ask questions about your codebase and get intelligent answers
* **Symbol Navigation** - Jump to function definitions, class declarations, and more

To enable indexing for a repository:

1. Go to **Settings > Repositories**
2. Select a repository from the list
3. Click **View Details** to open the repository page
4. Navigate to the **Settings** tab
5. Enable code indexing

See [Code Intelligence](/docs/features/code-intelligence) for details on what indexing enables.

## Issues & Pull Requests

Sync GitHub issues and pull requests to your Kasava Products for unified project management.

<Steps>
  <Step title="Create or Open a Product">
    Navigate to an existing Product or create a new one
  </Step>

  <Step title="Link GitHub Repository">
    In Product settings, click to link a GitHub repository
  </Step>

  <Step title="Select Repository">
    Choose from your connected repositories
  </Step>

  <Step title="Enable Issue Sync">
    Toggle on issue and PR syncing in the configuration
  </Step>
</Steps>

### Issue Features

Once synced, you can:

* View issue details, descriptions, and comments
* See and update assignees and labels
* Track issue status (open/closed)
* Link issues to Plans and other Kasava entities

### Pull Request Features

* View PR status, reviewers, and approval status
* See linked issues for each PR
* Check CI/CD status
* View merge status and conflicts

## GitHub Projects V2

Link GitHub Projects V2 boards to Kasava Products for enhanced Kanban management.

<Steps>
  <Step title="Open Product Settings">
    Navigate to your Product and click the settings icon
  </Step>

  <Step title="Link GitHub Project">
    In the external projects section, click **Link GitHub Project**
  </Step>

  <Step title="Select Project">
    Choose from available GitHub Projects V2 in your connected repositories
  </Step>

  <Step title="Configure Mapping">
    Kasava automatically maps Status fields to Kanban columns
  </Step>
</Steps>

### Kanban Board

Once linked, your Product's Kanban view shows issues organized by GitHub Project status:

* Drag and drop issues between columns to update their status
* Changes sync back to GitHub Projects in real-time
* View issues from multiple platforms side-by-side

### Field Mapping

| GitHub Field | Kasava Field     |
| ------------ | ---------------- |
| Status       | Kanban column    |
| Assignees    | Assignees        |
| Labels       | Labels           |
| Milestone    | Sprint/Iteration |

## Commit Analysis

Kasava uses AI to analyze commits and extract valuable insights:

### Commit Type Detection

Automatically categorizes commits:

* `feat` - New feature
* `fix` - Bug fix
* `refactor` - Code restructuring
* `docs` - Documentation changes
* `test` - Test additions or modifications
* `chore` - Maintenance tasks

### Impact Assessment

Each commit is rated for impact:

* **High** - Breaking changes, major features
* **Medium** - Notable improvements, significant fixes
* **Low** - Minor changes, small fixes

### Additional Analysis

* **Complexity Score** - Estimated complexity based on files changed and diff size
* **Business Value** - AI-assessed business impact of the change
* **Component Detection** - Which parts of your system are affected

### Personalized Analysis with AI Learning

Commit analysis automatically applies your [AI Learning patterns](/docs/advanced/ai-learning). When you correct how the AI categorizes commits:

* Future commits are classified according to your preferences
* File path patterns you've defined are respected
* Your terminology preferences are used in descriptions
* Severity thresholds match your standards

For example, if you've taught Kasava that commits to `src/core/**` should be classified as "high impact" rather than "medium", all future commits to that path will follow your preference.

<Tip>
  If a commit is miscategorized, correct it from the Activity tab. Over time, Kasava learns your project's conventions and improves automatically.
</Tip>

View commit analytics in the **Analytics** section of your repository.

## @kasava Commands in Issues

Use `@kasava` mentions in GitHub issue comments to trigger AI-powered actions directly from your workflow. This feature lets team members request summaries, generate documentation, and perform analysis without leaving GitHub.

### How It Works

1. Comment on any GitHub issue with `@kasava` followed by a command
2. Kasava detects the mention via webhooks
3. The AI processes your request using the issue context
4. Results are posted as a reply comment on the issue

### Built-in Commands

| Command               | Description                                      |
| --------------------- | ------------------------------------------------ |
| `@kasava summarize`   | Summarize the issue discussion and key decisions |
| `@kasava document`    | Generate documentation from the issue content    |
| `@kasava plan`        | Create an implementation plan for the issue      |
| `@kasava design-doc`  | Generate a design document                       |
| `@kasava prototype`   | Create a prototype spec from requirements        |
| `@kasava diagnose`    | Analyze and diagnose the problem described       |
| `@kasava postmortem`  | Generate a postmortem analysis                   |
| `@kasava insights`    | Extract key insights from the discussion         |
| `@kasava changelog`   | Generate changelog entries                       |
| `@kasava report`      | Create a status report                           |
| `@kasava review-prep` | Prepare materials for a review meeting           |
| `@kasava related`     | Find related issues in your repositories         |
| `@kasava impact`      | Analyze the potential impact of changes          |
| `@kasava link`        | Suggest links to relevant resources              |
| `@kasava sync-status` | Check synchronization status                     |

### Command Arguments

Commands support natural language arguments to filter or customize the output:

**Filter by recent comments:**

```
@kasava summarize last 5 comments
@kasava summarize last 10 comments
```

**Filter by date range:**

```
@kasava summarize since last week
@kasava summarize since 3 days ago
@kasava summarize since 2025-01-15
```

**Filter by participants:**

```
@kasava summarize between @alice and @bob
@kasava summarize by @charlie
```

**Filter by mentions:**

```
@kasava summarize mentioning @security-team
```

**Combine filters:**

```
@kasava summarize last 10 comments by @alice since last week
```

### Multiple Commands

You can trigger multiple commands in a single comment:

```
@kasava summarize
@kasava plan
```

Both commands will be processed and their results posted.

### Asking Questions

If you mention `@kasava` without a recognized command, it routes to the AI chat agent. You can ask free-form questions about the issue:

```
@kasava what are the main blockers here?
@kasava can you explain the proposed solution?
```

### Custom Commands

Organizations can create custom action types in **Settings > Templates > Action Types**. Custom commands extend the built-in set with organization-specific workflows.

Once created, custom commands work just like built-in ones:

```
@kasava my-custom-action
```

See [Settings](/docs/account/settings) for information on creating custom action types.

### Authorization

By default, only organization members can use `@kasava` commands. Administrators can enable external collaborators in **Settings > Integrations > Permissions**.

| User Type              | Default Access              |
| ---------------------- | --------------------------- |
| Organization members   | ✅ Allowed                   |
| External collaborators | ❌ Requires admin permission |

To enable external collaborators:

1. Go to **Settings > Integrations**
2. Find **Permission Settings**
3. Enable **Allow External Collaborators**

This setting can also be configured per-repository.

<Tip>
  Use `@kasava` commands in long issue threads to quickly catch up on discussions without reading every comment.
</Tip>

## Historical Sync

Sync and analyze your repository's history:

### Commit History Sync

<Steps>
  <Step title="Open Repository">
    Navigate to the repository you want to sync
  </Step>

  <Step title="Go to Settings">
    Click the repository settings
  </Step>

  <Step title="Enable Historical Sync">
    Turn on historical commit sync and select a date range
  </Step>

  <Step title="Monitor Progress">
    Watch the sync progress in the repository dashboard
  </Step>
</Steps>

Historical sync provides:

* Commit trends over time
* Author contribution patterns
* Change frequency analysis
* Complete project history

## Troubleshooting

<AccordionGroup>
  <Accordion title="Repository not showing up">
    Check that you've granted access to the repository during GitHub App installation. Go to **GitHub Settings > Applications > Kasava** to update repository access.
  </Accordion>

  <Accordion title="Issues not syncing to my Product">
    Verify that:

    1. The repository is linked to your Product
    2. Issue sync is enabled in Product settings
    3. The GitHub integration shows as connected
  </Accordion>

  <Accordion title="Indexing is stuck or failing">
    Large repositories may take longer to index. Check the sync status in the repository dashboard. If stuck, try clicking "Retry" to restart the indexing process.
  </Accordion>

  <Accordion title="Can't see a GitHub organization">
    You may need to request or grant organization access. In GitHub, go to **Settings > Applications > Kasava** and click "Request" or "Grant" next to the organization name.
  </Accordion>
</AccordionGroup>

## Permissions

The Kasava GitHub App requests these permissions:

| Permission          | Purpose                           |
| ------------------- | --------------------------------- |
| Repository contents | Read code for indexing and search |
| Issues              | Read and create issues            |
| Pull requests       | Read PR information               |
| Projects            | Access GitHub Projects V2         |
| Metadata            | Read repository information       |
| Webhooks            | Receive real-time updates         |

## Security

* GitHub App tokens are encrypted at rest
* Access can be revoked anytime in GitHub Settings > Applications
* Kasava never stores your GitHub password
* All API communication uses HTTPS

## Related

<CardGroup cols={2}>
  <Card title="Code Intelligence" icon="brain" href="/docs/features/code-intelligence">
    Learn about indexing and semantic search
  </Card>

  <Card title="Products" icon="layer-group" href="/docs/features/products">
    Link GitHub repositories to Products
  </Card>

  <Card title="AI Chat" icon="comments" href="/docs/features/ai-chat">
    Ask AI about your code and commits
  </Card>
</CardGroup>