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

# GitHub

> Connect your Github repositories to Gitar

export const ThemeImage = ({src, alt}) => {
  let lightSrc, darkSrc;
  if (src.includes("-light.")) {
    lightSrc = src;
    darkSrc = src.replace("-light.", "-dark.");
  } else if (src.includes("-dark.")) {
    darkSrc = src;
    lightSrc = src.replace("-dark.", "-light.");
  } else {
    lightSrc = src;
    darkSrc = src;
  }
  return <span>
      <img className="block dark:hidden rounded-lg border" src={lightSrc} alt={alt} />
      <img className="hidden dark:block rounded-lg border" src={darkSrc} alt={alt} />
    </span>;
};

## Install the Gitar GitHub App

GitHub repositories are connected to Gitar by installing the Gitar GitHub App. The app handles authentication, permissions, and webhook delivery so you do not need to manage tokens or secrets manually.

<ThemeImage src="/assets/images/conn-github-dark.png" alt="Connect GitHub" />

## Setup Instructions

<Steps>
  <Step title="Access Gitar Dashboard">
    Navigate to your organization settings or the onboarding flow in the Gitar dashboard. Click **Connect** for GitHub to begin the installation process.
  </Step>

  <Step title="Install the GitHub App">
    You will be redirected to GitHub to install the Gitar App. Select the GitHub organization where you want to install the app.
  </Step>

  <Step title="Select Repositories">
    Choose which repositories Gitar should have access to. You can grant access to **all repositories** in the organization or **select specific ones**.

    <Callout type="info" title="Changing Repository Access Later">
      You can modify which repositories the Gitar app can access at any time. Go to your GitHub organization **Settings -> Installed GitHub Apps -> Gitar -> Configure** to update repository access.
    </Callout>
  </Step>

  <Step title="Confirm Installation">
    Review and approve the installation on GitHub. Once confirmed, you will be redirected back to Gitar with the connection active.
  </Step>
</Steps>

## Permissions

When installing the Gitar GitHub App, you will be asked to grant certain permissions. These permissions are essential for Gitar to function properly.

**Read and Write Access to Code, Issues, and Pull Requests**

Gitar needs read and write access to your repository's code, issues, and pull requests. This enables Gitar to:

* Analyze your codebase and determine the changes it needs to make
* Create and manage pull requests and issues related to code maintenance tasks
* Push code changes to branches

Importantly, Gitar **does not save or store any of your code** on its servers. Code is checked out, processed, and discarded.

**Read and Write Access to Actions, Checks, Commit Statuses, and Workflows**

Gitar requires both read and write access to actions, checks, commit statuses, and workflows to monitor and manage your repository's build process. This allows Gitar to:

* Introspect GitHub Actions logs and diagnose build failures
* Read PR comments and review feedback
* Fix build errors and address code review feedback automatically
* Improve the quality of its PRs by responding to CI results

## GitHub Enterprise Server

Gitar supports GitHub Enterprise Server installations. If your organization uses GitHub Enterprise Server, contact [developers@gitar.ai](mailto:developers@gitar.ai) for setup assistance.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Gitar isn't processing my PRs">
    Verify that the GitHub App is installed on the correct organization and has access to the repository in question. In your GitHub organization, go to **Settings -> Installed GitHub Apps** and confirm the Gitar app is listed and configured for the expected repositories.
  </Accordion>

  <Accordion title="Permission errors when Gitar pushes">
    Ensure the GitHub App has write access to the repository. If you are using branch protection rules, you may need to add the Gitar app to the bypass list so it can push commits and update protected branches.
  </Accordion>

  <Accordion title="I need to change which repositories Gitar accesses">
    Go to your GitHub organization **Settings -> Installed GitHub Apps -> Gitar -> Configure** to modify repository access. Changes take effect immediately.
  </Accordion>
</AccordionGroup>