GitHub Connector Tools

​

Overview

​

Tool Name

github_connector_tools

​

Purpose

​

Functions Available

1. git_action: Core Git operations including repository management, branching, committing, and history tracking.
2. file: File operations for reading, writing, searching, and managing repository content.
3. git_action (GitHub-specific actions): GitHub platform features including pull requests, remote repository management, and credential storage.

​

Key Features

​

Input Parameters for Each Function

​

git_action

​

file

​

Use Cases

1. Automated Documentation Generate and commit data dictionaries, analysis reports, or pipeline documentation directly to GitHub repositories.
2. Code Generation & Versioning Create dbt models, SQL scripts, or Python notebooks and version them in GitHub for team collaboration.
3. Data Pipeline Deployment Clone configuration repositories, update parameters, commit changes, and create pull requests for review.
4. Collaborative Data Projects Share analysis notebooks, datasets, and findings with team members through structured GitHub workflows.
5. Backup & Disaster Recovery Automatically commit critical configurations, metadata, and artifacts to GitHub for version-controlled backups.

​

Workflow/How It Works

1. Step 1: Authenticate with GitHub Store GitHub credentials securely using Personal Access Token:
   git_action(
       action="store_github_credentials",
       username="your_github_username",
       token="ghp_your_personal_access_token"
   )
   
2. Step 2: Create or Clone Repository Start with a new repository or clone an existing one:
   # Create new repository
   git_action(
       action="create_repo",
       repo_id="my_data_project"
   )
   
   # Or clone from GitHub
   git_action(
       action="clone_repo",
       repo_id="analytics_pipeline",
       url="https://github.com/organization/analytics-pipeline.git"
   )
   

3. Step 3: Manage Files Create, read, and organize files within the repository:
   # Write documentation
   file(
       action="write",
       repo_id="my_data_project",
       file_path="docs/data_dictionary.md",
       content="# Data Dictionary\n\n## Customer Table\n..."
   )
   
   # Search for files
   file(
       action="find",
       repo_id="my_data_project",
       pattern="*.sql"
   )
   
4. Step 4: Commit Changes Track changes with descriptive commit messages:
   git_action(
       action="commit",
       repo_id="my_data_project",
       commit_message="Add customer data dictionary and initial ETL scripts"
   )
   

5. Step 5: Create Pull Request Collaborate with team through pull requests:
   git_action(
       action="create_pull_request",
       repo_id="my_data_project",
       branch_name="feature/new-pipeline",
       title="Add new customer segmentation pipeline",
       body="This PR introduces customer segmentation logic with dbt models."
   )
   
6. Step 6: Push to GitHub Sync local changes to remote repository:
   git_action(
       action="push",
       repo_id="my_data_project"
   )
   

​

Integration Relevance

• project_manager_tools to track data projects and link GitHub repositories to missions.
• data_connector_tools to export analysis results and commit them to version control.
• dbt_action to manage dbt projects in GitHub with full version control.
• file_manager_tools to organize artifacts before committing to repositories.
• slack_tools to notify teams when pull requests are created or commits are pushed.

​

Configuration Details

• Personal Access Token: Generate from GitHub Settings → Developer settings → Personal access tokens. Required scopes: repo, workflow.
• Enterprise URL (enterprise_url): Optional on saved GitHub connections (PAT, User OAuth, and GitHub App). Leave blank for public github.com. Set to your GitHub Enterprise Server hostname (for example https://github.mycompany.com) when repositories and API calls target a self-hosted instance. A blank Enterprise URL uses the server’s default GitHub address, which is public GitHub unless the server was started with its own. On a server whose default is public GitHub, a github.com address (such as an organisation page) is refused when the connection is saved, because it would be ignored and cannot select an organisation; on a server whose default is a GitHub Enterprise Server, blank means that server, and a github.com address selects public GitHub and is accepted. Connections already saved with a github.com address keep working against api.github.com, and Genesis appends /api/v3 only for Enterprise Server hosts.
• Git Commit Author (git_author_mode): Optional select field on the saved GitHub connection. Default: genesis_bot. Supported values: genesis_bot, authenticated_git_user, custom.
• Git Author Name (git_author_name) and Git Author Email (git_author_email): Optional string fields on the saved GitHub connection. Genesis shows them only when git_author_mode="custom", and both are required together in that mode. For GitHub App connections, use custom when you need a fixed verified author identity.
• Repository Naming: Use lowercase with hyphens (e.g., data-pipeline-prod) for consistency.
• Branch Strategy: Use feature branches (feature/, bugfix/) for changes; protect main branch.
• Commit Messages: Follow conventional commits format: feat:, fix:, docs:, refactor:.
• File Paths: Always use forward slashes (/) and relative paths without leading slash.
• Large Files: GitHub has 100MB file size limit; use Git LFS for larger artifacts or store in data platforms.

​

Limitations or Notes

1. File Size Limits: GitHub limits individual files to 100MB; repositories to 1GB recommended size.
2. API Rate Limits: GitHub API has rate limits (5,000 requests/hour for authenticated users); batch operations when possible.
3. Private and Internal Repository Access: Requires appropriate permissions and PAT scopes for non-public repos.
4. Binary Files: Git is optimized for text files; large binary files can slow repository performance.
5. Merge Conflicts: Automatic merging may fail with conflicts; manual resolution required.
6. Branch Protection: Protected branches may prevent direct pushes; use pull requests instead.
7. Network Dependency: All operations require internet connectivity to GitHub servers.

​

Supported Actions

​

Not Supported

​

Output

• clone_repo: Confirmation with repository path and clone details.
• commit: Commit hash, files changed, and commit message confirmation.
• push: Push status, branch name, and remote URL.
• get_history: List of commits with hash, author, date, and message.
• get_status: Current branch, staged/unstaged files, and sync status.
• create_pull_request: PR number, URL, and creation confirmation.
• get_pull_request_info: PR metadata plus CI status for the head commit. Returns number, title, body, state, merged, user, head_branch, base_branch, head_sha (the real PR head commit — never merge_commit_sha), url, created_at, updated_at, merged_at, and merge_commit_sha under its own key. CI status for head_sha is reported as:
  • check_runs — a list of {name, status, conclusion, details_url}.
  • check_runs_total and check_runs_truncated — GitHub’s reported Check-run count and whether the bounded check_runs list is incomplete or disagrees with that count.
  • combined_status — {state, total_count, truncated, statuses:[{context, state, target_url}]}. state is GitHub’s commit-status rollup, which covers commit statuses only. total_count is how many status contexts GitHub reports, and truncated is true when the observed count disagrees with that total or the bounded walk cannot prove completeness — so a partial list is never mistaken for a complete one. (GitHub defaults to 30 statuses per page and permits up to 100; Genesis requests the maximum and continues the paginated feed.)
  • ci_summary — the derived rollup across both sources: {state, check_runs_total, check_runs_failed, check_runs_pending, check_runs_truncated, statuses_total, statuses_failed, statuses_pending, statuses_truncated, truncated}. state is failure when any check run or current status did not pass, pending when nothing failed but a signal is unfinished, incomplete, or semantically unknown, success when every known signal finished and passed and both sources are complete, and no_checks when neither source reported anything. Prefer ci_summary.state over combined_status.state for “did CI pass?”: GitHub does not fold check runs into the commit-status rollup, so combined_status.state can read success while GitHub Actions is still running.
  A failure to read one CI feed degrades gracefully rather than failing the call or discarding the other feed: only the failed source’s fields are set to null, the successful peer remains available, and ci_summary is null because the aggregate is incomplete. check_runs_error or commit_statuses_error carries the source-specific reason, and the rest of the PR metadata is still returned. On a non-rate-limited 403 the message names the grant to add, and which grant depends on the connection: a GitHub App connection is told to add Checks: read or Commit statuses: read to the installation, while a PAT or User OAuth connection is told which token scope it needs. Rate-limited and other failures report a generic read-failure message. See Connections — Permissions for reading CI results.
• list_remote_repos: Accessible personal and organization repositories plus summary. Each repo includes both private and visibility, and summary includes total_accessible_repos, personal_repos_count, organizations_count, and visibility_breakdown.
• check_remote_repo_exists: Successful responses include repository metadata with both private and visibility.
• create_remote_repo: Successful responses include created repository metadata with private, visibility, default_branch, url, ssh_url, and web_url.
• READ_FILE: Direct branch reads return content, text, text_is_lossy, sha, size, encoding, ref, path, and source. Missing refs or files return error_code="REMOTE_FILE_NOT_FOUND"; directory paths return error_code="PATH_IS_DIRECTORY". Rate-limited reads can return error_code="RATE_LIMITED" with retry_after_seconds.
• file operations: Success confirmation, file paths, content previews, batch read results with per-file success or error details plus content and size for successful reads. Batch reads can also surface per-file truncated, truncation_info, continuation, encoding, file_type, total_size, returned_size, returned_lines, total_lines, start_line, end_line, start_byte, end_byte, and freshness_notice when a managed checkout has no git remote, plus top-level warnings, files_truncated, files_skipped, skipped_preview, and continuation_hint when the response is cut short. On managed GitHub repos, origin-backed file(action="read") can also return branch_name, sha, _remote_read, and _remote_read_window; when the checkout has no git remote, responses include freshness_notice and may set source to local_tree. When return_base64=true, the response includes encoding="base64".
• Large path and archive previews: file(action="list") and file(action="find") can return files_preview, files_truncated, files_omitted_count, total_files, files_continuation_hint, note, and narrowing_hint when many paths match. file(action="unzip") can similarly preview extracted_files and download_links with fields such as extracted_files_preview, extracted_files_truncated, extracted_files_omitted_count, total_extracted_files, extracted_files_continuation_hint, download_links_preview, download_links_truncated, download_links_omitted_count, total_download_links, and download_links_continuation_hint.
• Zero-result repo search warning: git_action(action="search"), git_action(action="grep"), file(action="search"), and file(action="fast_search") can include _branch_warning when a repo on a non-default branch returns 0 matches. The object includes current_branch, default_branch, and message, which directs you to switch to the default branch, run git_action(action="pull"), and retry the search.
• Managed-remote search freshness: On managed GitHub repos, git_action(action="search") and git_action(action="grep") against the managed base checkout run against refreshed origin state instead of the shared local clone. Searches against a WIP worktree still use that worktree. When the checkout has no git remote, file(action="fast_search") searches the local checkout and includes freshness_notice.
• list_repos: Repository ids by default. With details=true, each detail row includes mode, has_git_dir, has_remote, scope, owner_user_id, owner_bot_id, and undeletable, plus credentials-redacted remote_url when present, clone_source when Genesis can infer the remote platform, and path when include_paths=true.
• Errors: Detailed error messages with resolution guidance (e.g., authentication failures, merge conflicts).

​

Best Practices

​

Example: Complete Data Project Workflow

# 1. Store GitHub credentials (one-time setup)
git_action(
    action="store_github_credentials",
    username="data_engineer",
    token="ghp_abc123..."
)

# 2. Clone existing project repository
git_action(
    action="clone_repo",
    repo_id="customer_analytics",
    url="https://github.com/company/customer-analytics.git"
)

# 3. Create feature branch for new analysis
git_action(
    action="create_branch",
    repo_id="customer_analytics",
    branch_name="feature/churn-analysis"
)

git_action(
    action="switch_branch",
    repo_id="customer_analytics",
    branch_name="feature/churn-analysis"
)

# 4. Create analysis notebook
file(
    action="write",
    repo_id="customer_analytics",
    file_path="notebooks/churn_analysis.py",
    content="""
# Customer Churn Analysis
import pandas as pd

# Load data
customers = pd.read_csv('data/customers.csv')

# Analysis logic...
"""
)

# 5. Create documentation
file(
    action="write",
    repo_id="customer_analytics",
    file_path="docs/churn_methodology.md",
    content="# Churn Analysis Methodology\n\n## Overview\n..."
)

# 6. Commit changes
git_action(
    action="commit",
    repo_id="customer_analytics",
    commit_message="feat: Add customer churn analysis with documentation"
)

# 7. Push to GitHub
git_action(
    action="push",
    repo_id="customer_analytics",
    branch_name="feature/churn-analysis"
)

# 8. Create pull request for review
git_action(
    action="create_pull_request",
    repo_id="customer_analytics",
    branch_name="feature/churn-analysis",
    title="Add Customer Churn Analysis",
    body="This PR adds:\n- Churn prediction model\n- Analysis notebooks\n- Documentation"
)

# 9. Check repository status
git_action(
    action="get_status",
    repo_id="customer_analytics"
)

​

Advanced Features

​

Bulk File Operations

file(
    action="copy",
    repo_id="customer_analytics",
    source_patterns=["*.sql", "*.py"],
    target_path="archive/",
    preserve_structure=True
)

file(
    action="copy",
    repo_id="customer_analytics",
    source_patterns=["reports/monthly/summary.md"],
    target_path="archive/",
    preserve_structure=True
)
# Writes archive/summary.md

file(
    action="read_multiple",
    repo_id="customer_analytics",
    files=[
        "ddl/customers.sql",
        {"path": "ddl/orders.sql"},
        "models/product_dim.sql",
    ]
)

​

Search Across Files

file(
    action="search",
    repo_id="customer_analytics",
    pattern="SELECT.*FROM customers",
    regex=True
)

​

Fetch Deep History

git_action(
    action="fetch_more_history",
    repo_id="customer_analytics",
    depth=100
)

git_action(
    action="get_history",
    repo_id="customer_analytics",
    max_count=50
)

​

List Remote Repositories

git_action(
    action="list_remote_repos",
    include_orgs=True
)

​

Troubleshooting