​
GitHub Integration

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.

​
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

​
Prerequisites

  • A GitHub account with access to repositories you want to connect
  • Admin permissions to install GitHub Apps in your repositories or organization
  • An active Overcut workspace

​
Setup

1

Start GitHub Connection

In your Overcut workspace, go to Integrations and click Connect GitHub.
2

Install the Overcut GitHub App

Click Connect to be redirected to GitHub. Choose whether to install the app for your personal account or specific organizations. Grant the necessary permissions for repositories and issues.
3

Select Repositories

Choose which repositories the Overcut app should have access to. You can select all repositories or specific ones based on your needs.
4

Complete the Setup

After installing the app and selecting repositories, you’ll be redirected back to Overcut. The connection will be established and you can start using GitHub in your workflows.

​
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
For workflows that need to automatically identify which code repositories are most relevant to GitHub issues, consider using the repo.identify 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 Repository Mapping guide.

​
Working with Repositories

​
Cloning Code

Agents can clone GitHub repositories using the git.clone action: 
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:
SettingDefaultPurpose
Agent image(workspace default)Override the Docker image used to run agents
Enable cachefalsePersist build artefacts to speed up subsequent runs
Cache dependenciesfalseInclude dependency directories (e.g., node_modules)
Tools[]Define repo-specific commands like lint, test, install
Custom instructionsnullInject 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

The Overcut GitHub App requests the following permissions:

​
Repository Access

  • Contents: Read and write access to repository code
  • Issues: Read and write access to issues and comments
  • Pull Requests: Read and write access to pull requests and reviews
  • Metadata: Read access to repository metadata

​
Organization Access

  • Members: Read access to organization members (for assignment features)
  • Organization: Read access to organization information
These permissions allow Overcut to fully integrate with your GitHub workflow while maintaining security and following GitHub’s best practices.

​
Advanced Features

​
Sparse Checkout

For large repositories, use sparse checkout to focus on specific components: 
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: 
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

​
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 Overcut 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 you have access to
  • Check your GitHub user permissions for specific repositories
  • Verify the repository names are correctly configured

​
Webhook Issues

  • Ensure webhooks are properly configured in your GitHub repositories
  • Check that the Overcut app has webhook permissions
  • Verify webhook URLs are accessible from GitHub’s servers

​
Getting Help

If you encounter issues with the GitHub integration:
  1. Check the troubleshooting section above
  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