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

# GitHub App Setup

> Connect a GitHub repository so the UserJourneys AI agent can read code, make changes, and create draft pull requests.

Connect the UserJourneys GitHub App to the repository you want the AI agent to use. After setup, the agent can read your codebase, prepare code changes, and create draft pull requests for your review.

## Before you start

You need:

* Access to the UserJourneys project you want to configure
* Permission to install GitHub Apps on the target GitHub account or organization
* The repository you want UserJourneys to use

<Info>
  The GitHub App is the recommended connection method. Use a Personal Access Token only when your organization cannot install the GitHub App.
</Info>

## Connect the GitHub App

<Steps>
  <Step title="Open UserJourneys settings">
    Sign in to <a href="https://app.userjourneys.ai/settings/setup" target="_blank" rel="noreferrer">UserJourneys settings</a>. You can also open **Settings** from the sidebar in the app.
  </Step>

  <Step title="Open Setup">
    Select the **Setup** tab.
  </Step>

  <Step title="Start the GitHub connection">
    In the **GitHub** section, click **Connect GitHub App**.
  </Step>

  <Step title="Choose the GitHub account">
    GitHub opens the <a href="https://github.com/apps/userjourneys-ai" target="_blank" rel="noreferrer">UserJourneys GitHub App</a> installation page. Choose the personal account or organization that owns the repository.
  </Step>

  <Step title="Select repository access">
    Choose the repository UserJourneys should use.

    <Tip>
      Select only the repository you want the AI agent to work with unless your team intentionally wants to grant broader access.
    </Tip>
  </Step>

  <Step title="Approve the installation">
    Click **Install** or **Save** in GitHub. GitHub sends you back to UserJourneys.
  </Step>

  <Step title="Choose the repository in UserJourneys">
    If UserJourneys shows a repository picker, select the repository and click **Use Repository**.
  </Step>

  <Step title="Confirm the connection">
    The **GitHub** section shows the connected repository name.
  </Step>
</Steps>

<Check>
  The AI agent can now use the connected repository to read code and create draft pull requests for approved code changes.
</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="I cannot install the GitHub App">
    Ask a GitHub organization owner or app manager to install the app, or request permission to install GitHub Apps for the organization.
  </Accordion>

  <Accordion title="No repositories appear after installing">
    The GitHub App may not have access to any repositories. In UserJourneys, click **Reload Repositories**. If the list is still empty, reinstall or update the GitHub App in GitHub and grant access to the repository you want to connect.
  </Accordion>

  <Accordion title="I connected the wrong repository">
    Go to **Settings > Setup > GitHub**, click **Disconnect**, then connect the GitHub App again and choose the correct repository.
  </Accordion>

  <Accordion title="I need a fallback connection method">
    Use **Personal Access Token** from the GitHub section in UserJourneys. Prefer the GitHub App when possible because it gives your team clearer installation ownership and repository-scoped access.
  </Accordion>
</AccordionGroup>