Connect to GitHub

​

What You Can Do

• 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?

​

Using GitHub in Your Workflows

• 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

​

Working with Repositories

​

Trigger GitHub Actions from Overcut

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"

​

Cloning Code

steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "owner/repository-name"
      branch: "main"
      cloneOptions:
        depth: 1
        singleBranch: true

​

Repository Configuration

​

Working with Issues and Pull Requests

​

GitHub Issues

• 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

• 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

​

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

• 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

• GitHub on Overcut Cloud
• GitHub from self-hosted Overcut

​

Advanced Features

​

Sparse Checkout

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

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 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

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