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

# Connect to GitHub

> Connect Overcut to your GitHub repositories and issues to manage code, pull requests, and project tracking directly from your workflows.

Connect Overcut to your GitHub repositories and issues to seamlessly integrate source code management and project tracking into your workflows. Once connected, agents can discover your GitHub repositories, work with code directly, and manage issues and pull requests.

This page covers the concepts that apply to every GitHub connection. **The exact
setup steps depend on where Overcut runs** - pick your path in
[Which setup do I need?](#which-setup-do-i-need) below.

## What You Can Do

With GitHub connected, Overcut agents can:

* **Access Repositories**: Clone, read, and modify code in your GitHub repositories
* **Manage Issues**: Create, update, and comment on GitHub issues
* **Handle Pull Requests**: Review, comment on, and manage pull requests
* **Code Operations**: Clone repositories, create branches, and perform git operations
* **Webhook Triggers**: Automatically start workflows based on GitHub events
* **Repository Configuration**: Configure agent behavior per repository

## Which setup do I need?

One question decides your path: **where Overcut runs**.

| Where Overcut runs      | Follow this guide                                                        |
| ----------------------- | ------------------------------------------------------------------------ |
| Overcut Cloud (managed) | [GitHub on Overcut Cloud](/docs/integrations/github/cloud)               |
| Self-hosted Overcut     | [GitHub from self-hosted Overcut](/docs/integrations/github/self-hosted) |

<CardGroup cols={2}>
  <Card title="GitHub on Overcut Cloud" icon="cloud" href="/docs/integrations/github/cloud">
    Managed Overcut. Install the managed Overcut GitHub App. No credentials to
    manage.
  </Card>

  <Card title="GitHub, self-hosted Overcut" icon="server" href="/docs/integrations/github/self-hosted">
    Overcut on your own infrastructure. Create your own GitHub App and configure
    the deployment with its credentials.
  </Card>
</CardGroup>

## Using GitHub in Your Workflows

Once connected, GitHub repositories will appear as available sources when you:

* Add a **Source** to a workflow
* Configure a **Trigger** that monitors GitHub events
* Set up **Actions** that work with code or issues

### Example Workflows

* **Code Review Automation**: Automatically review pull requests and provide feedback
* **Issue Triage**: Convert GitHub issues to structured tasks or create follow-up tickets
* **Documentation Updates**: Keep documentation in sync with code changes
* **Release Management**: Track all issues and PRs related to a specific release
* **Bug Investigation**: Clone repositories and analyze code to understand reported issues

<Note>
  For workflows that need to automatically identify which code repositories are most relevant to GitHub issues, consider using the <code>repo.identify</code> action. This action uses AI-powered analysis and repository correlations to determine the best repositories to work with for each issue. Learn more in our <a href="/docs/repositories/repository-mapping">Repository Mapping guide</a>.
</Note>

## Working with Repositories

### Trigger GitHub Actions from Overcut

Overcut can **directly trigger a GitHub Actions workflow** as part of your automation.  Add a `ci.executeWorkflow` step to your workflow and specify the repository, workflow file, ref (branch or tag) and any inputs your Action expects.

```yaml theme={null}
steps:
  - id: "build-and-test"
    name: "Build & Test (GitHub Actions)"
    action: "ci.executeWorkflow"
    params:
      provider: "github"
      repoFullName: "owner/repo"
      workflowId: "ci.yml"          # can be the file name or a run-id
      ref: "main"                  # branch, tag or SHA
      waitForCompletion: true        # set false for fire-and-forget
      inputs:
        node-version: "18"
        run-tests: "true"
```

When `waitForCompletion` is `true`, the step enters a **Waiting for External** status until GitHub reports the workflow finished.  See the dedicated documentation for full parameter list and advanced options: **[Execute CI Workflow](/docs/workflows/ci-execute-workflow)**.

### Cloning Code

Agents can clone GitHub repositories using the `git.clone` action:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "owner/repository-name"
      branch: "main"
      cloneOptions:
        depth: 1
        singleBranch: true
```

### Repository Configuration

Each connected repository exposes a **Configuration** panel where workspace admins can override agent behavior:

| Setting                 | Default               | Purpose                                                                                            |
| ----------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
| **Agent image**         | *(workspace default)* | Choose the container environment agents run in. See [Agent Image](/docs/repositories/agent-image). |
| **Enable cache**        | `false`               | Persist build artefacts to speed up subsequent runs                                                |
| **Cache dependencies**  | `false`               | Include dependency directories (e.g., `node_modules`)                                              |
| **Tools**               | `[]`                  | Define repo-specific commands like `lint`, `test`, `install`                                       |
| **Custom instructions** | `null`                | Inject additional workflow steps (YAML/Markdown)                                                   |

## Working with Issues and Pull Requests

### GitHub Issues

Agents can work with GitHub issues through:

* **Issue Creation**: Create new issues with descriptions, assignees, and labels
* **Issue Updates**: Modify existing issues and change their status
* **Comments**: Leave comments on issues with rich text formatting
* **Label Management**: Add, remove, and manage issue labels
* **Assignee Management**: Assign and unassign team members

### Pull Requests

Agents can handle pull requests by:

* **Code Review**: Analyze code changes and provide feedback
* **Comment Integration**: Add inline and general comments on PRs
* **Status Updates**: Track PR lifecycle from creation to merge
* **Automated Checks**: Run tests, linting, and validation

## Webhook Triggers

GitHub integration enables automatic workflow triggers based on repository events:

### Issue Events

* `issue_opened` - Issue was created
* `issue_closed` - Issue was closed
* `issue_edited` - Title or body changed
* `issue_assigned` - Assignee added
* `issue_unassigned` - Assignee removed
* `issue_labeled` - Label was added
* `issue_unlabeled` - Label was removed
* `issue_commented` - New comment was posted

### Pull Request Events

* `pull_request_opened` - Pull request was opened
* `pull_request_closed` - Pull request was closed without merge
* `pull_request_merged` - Pull request was merged into base
* `pull_request_edited` - Title or description of PR was changed
* `pull_request_reviewed` - A review was submitted
* `pull_request_commented` - A comment was posted on the PR

### Slash Commands

Trigger workflows manually using slash commands in GitHub comments:

* Use `@overcut /command` in issue or PR comments
* Commands execute immediately for responsive user experience
* Works across all platforms: GitHub, Jira, GitLab, and more

## Permissions

In every setup, the GitHub App Overcut connects through needs read and write
access to repository contents, issues, pull requests, and Actions, plus read
access to metadata and organization members. **Who owns the app differs by
path** (on Overcut Cloud it is the managed Overcut app; self-hosted deployments
create their own), so the exact configuration is listed on each connection
guide:

* [GitHub on Overcut Cloud](/docs/integrations/github/cloud)
* [GitHub from self-hosted Overcut](/docs/integrations/github/self-hosted)

## Advanced Features

### Sparse Checkout

For large repositories, use sparse checkout to focus on specific components:

```yaml theme={null}
steps:
  - id: "clone-large-repo"
    name: "Clone Large Repository"
    action: "git.clone"
    params:
      repoFullName: "company/monorepo"
      cloneOptions:
        sparseCheckout:
          enabled: true
          paths:
            - "src/frontend"
            - "docs"
            - "scripts"
```

### Partial Cloning

Optimize cloning performance with partial clone filters:

```yaml theme={null}
cloneOptions:
  depth: 1                    # Shallow clone (latest commit only)
  singleBranch: true          # Clone only the specified branch
  filter:
    type: "blob:none"         # Exclude binary files
    size: "100M"              # Skip files larger than 100MB
```

## Troubleshooting

General issues are covered below. For path-specific problems (app
configuration, callback URLs, webhook setup), see the troubleshooting section
on your connection guide.

### Connection Issues

* Ensure you have admin permissions in your GitHub organization
* Try disconnecting and reconnecting the integration
* Check that your GitHub account is accessible and not rate-limited

### Permission Errors

* Verify the connected GitHub App has the necessary permissions in GitHub
* Check that you're trying to access repositories you have access to
* Ensure your GitHub user account has appropriate permissions

### Missing Repositories

* The integration only shows repositories included in the app installation
* Check your GitHub user permissions for specific repositories
* Verify the repository names are correctly configured

## Getting Help

If you encounter issues with the GitHub integration:

1. Check the troubleshooting section on your connection guide
2. Review your GitHub permissions and repository access
3. Contact Overcut support with specific error messages
4. Ensure your GitHub account is active and accessible
5. Check GitHub's status page for any service issues

## Best Practices

### Repository Organization

* Use consistent naming conventions for repositories
* Organize repositories by team or project
* Set up branch protection rules for important branches

### Workflow Design

* Start with simple triggers and gradually add complexity
* Use delays for issue/PR creation to allow complete context
* Test workflows in development repositories first

### Security Considerations

* Regularly review app permissions and repository access
* Use organization-level installations for team-wide access
* Monitor workflow execution logs for unexpected behavior