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

# GitHub

> Connect your GitHub account to Workshop for repository access and API operations.

## Overview

The GitHub connector lets you link your GitHub account to Workshop using a Personal Access Token. Once connected, you can access repositories, analyze code, clone repos, and perform API operations through natural conversation.

<Info>
  **This is different from GitHub Integration.** The GitHub *connector* gives the Workshop agent API access to your repositories and issues via a Personal Access Token. [GitHub Integration](/workshop-cloud/github-integration) is the app-level feature for push/pull syncing between your Workshop project and a GitHub repo — it uses a GitHub App OAuth flow, not a PAT.
</Info>

## What You'll Need

| Credential                | Description                          | Format                                                 |
| ------------------------- | ------------------------------------ | ------------------------------------------------------ |
| **Personal Access Token** | Fine-grained or classic GitHub token | `ghp_...` (classic) or `github_pat_...` (fine-grained) |

## Creating a Personal Access Token

<Steps>
  <Step title="Open GitHub settings">
    Sign in to [github.com](https://github.com), click your profile photo, and select **Settings**.
  </Step>

  <Step title="Navigate to developer settings">
    Scroll down the sidebar and click **Developer settings > Personal access tokens > Fine-grained tokens**.
  </Step>

  <Step title="Generate a token">
    Click **Generate new token**. Enter a **Token name** (e.g., "Workshop Access"), set an **Expiration** date, and choose the **Resource owner** (your account or an organization).
  </Step>

  <Step title="Set repository access">
    Under **Repository access**, select which repositories the token can access.
  </Step>

  <Step title="Set permissions">
    Under **Permissions**, grant the access you need:

    * **Contents:** Read (to view files)
    * **Metadata:** Read (required for all tokens)
    * **Issues:** Read and write (if you want Workshop to create/manage issues)
    * **Pull requests:** Read and write (if you want Workshop to create PRs)
  </Step>

  <Step title="Copy the token">
    Click **Generate token** and copy it immediately. GitHub only shows the token once.
  </Step>
</Steps>

<Info>
  **Organization tokens may require approval.** If you select an organization as the resource owner, the organization may need to approve the token before it becomes active. Check with your organization administrator if the token isn't working.
</Info>

## Connecting to Workshop

<Steps>
  <Step title="Open the Hub">
    Open the **Workshop Hub** from the sidebar.
  </Step>

  <Step title="Go to Connectors">
    Click the **Connectors** tab.
  </Step>

  <Step title="Select GitHub">
    Click the **GitHub** card.
  </Step>

  <Step title="Enter details">
    Enter a **Connection Name** (e.g., "My GitHub Account") and paste your **Personal Access Token**.
  </Step>

  <Step title="Save">
    Click **Add Connection**.
  </Step>
</Steps>

## Using Your Connection

Once connected, you can ask Workshop to work with your GitHub data:

```
Using my GitHub connection, list all my repositories
```

```
Show me the README from my project-name repository
```

```
What are the open issues in my app repository?
```

```
Using my GitHub connection, clone my website repo and help me understand its structure
```

## Security Best Practices

* Use **fine-grained tokens** with the minimum permissions needed
* Set an **expiration date** on all tokens
* Create separate tokens for different integrations
* If you suspect a token is compromised, revoke it immediately in **GitHub Settings > Developer settings > Personal access tokens**

<Warning>
  GitHub automatically scans for leaked tokens and may revoke them. Never commit tokens to version control or share them publicly.
</Warning>

## Troubleshooting

| Issue                 | Solution                                                                                       |
| --------------------- | ---------------------------------------------------------------------------------------------- |
| "Bad credentials"     | Verify the token was copied correctly and hasn't expired or been revoked.                      |
| "Not Found" for repos | Ensure the token has access to the target repository.                                          |
| Rate limiting         | GitHub limits API requests to 5,000/hour for authenticated users. Wait for the limit to reset. |

## Learn More

* [GitHub Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
* [Fine-grained Token Permissions](https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens)