> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GitHub Connector Tools
> Seamlessly integrate GitHub repositories with Genesis Data Agents for version control, collaboration, and automated workflows.
## **Overview**
### **Tool Name**
```json theme={null}
github_connector_tools
```
### **Purpose**
The **github\_connector\_tools** enable direct integration between Genesis Data Agents and GitHub repositories. Manage repositories, files, branches, pull requests, and workflows programmatically—all within your data agent conversations. Perfect for automated documentation, code generation, data pipeline versioning, and collaborative data projects.
When a governed GitHub write is refused by GitHub itself, Genesis reports the
action as `not_applied` and preserves GitHub's error message for the reviewer.
An error after the write was sent, including an uncertain response, remains
ambiguous; do not retry until the action is reconciled. For GitHub-specific
actions, read-back uses the resolved GitHub credential, and Genesis confirms a
child-resource change only when its repository is visible to that credential.
A GitHub 404 is inconclusive because the repository may be private or missing.
Core `git_action` writes use the Git transport and cannot currently prove that
read-back uses the same credential, so an uncertain result remains
`reconciliation_required` rather than being automatically confirmed.
#### **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
Clone, create, list, and delete repositories with full version control integration.
Create, switch, merge branches and manage parallel development workflows.
Create, review, merge, and close pull requests programmatically for collaborative workflows.
Read, write, search, copy, move, and delete files with pattern matching and bulk operations.
Access commit logs, fetch history, and track changes across repository timelines.
Store GitHub credentials securely with support for Personal Access Tokens (PAT).
## **Input Parameters for Each Function**
### **`git_action`**
**Parameters**
| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | Git operation to perform. Values: `commit`, `get_history`, `create_branch`, `switch_branch`, `get_status`, `clone_repo`, `list_repos`, `pull`, `push`, `create_pull_request`, etc. | String (required) |
| **repo\_id** | Repository identifier. Required for most operations except `list_repos` and credential storage. | String |
| **commit\_message** | Message for commit action. | String |
| **co\_authors** | Optional array of strings in `Name ` format to add `Co-authored-by:` trailers when `action="commit"`. | Array |
| **branch\_name** | Name of branch for `clone_repo`, create/switch/pull/push operations, or the pull request source (head) branch. | String |
| **target\_branch** | Base/destination branch a `create_pull_request` merges into. Provider-agnostic; defaults to the repository default branch when omitted. Alias: `base_branch`. | String |
| **base\_branch** | Alias for `target_branch`. If both are supplied, `target_branch` wins. | String |
| **url** | Git repository URL for cloning or remote operations. | String |
| **shallow** | For `clone_repo`: perform a shallow clone. Default: `true`. | Boolean |
| **single\_branch** | For `clone_repo`: clone only the selected/default branch. Default: `true`. | Boolean |
| **depth** | For `clone_repo`: number of commits to fetch. `0` requests full history and overrides `shallow`. | Integer |
| **max\_count** | Maximum number of commits to return in history (for `get_history`). | Integer |
| **details** | For `list_repos`: include per-repo details. Default: `false`. Adds `mode`, `has_git_dir`, `has_remote`, `remote_url`, `clone_source`, `scope`, `owner_user_id`, `owner_bot_id`, and `undeletable`. | Boolean |
| **include\_paths** | For `list_repos` with `details=true`: include filesystem path. Default: `false`. | Boolean |
| **include\_orgs** | For `list_remote_repos`: include organization repositories in addition to personal repositories. Default: `true`. | Boolean |
| **repo\_name** | For `check_remote_repo_exists` and `create_remote_repo`: remote GitHub repository name. | String |
| **owner** | For `check_remote_repo_exists`: owner or organization that contains the repository. Optional. | String |
| **org** | For `create_remote_repo`: organization name when creating the repository outside your personal account. | String |
| **description** | For `create_remote_repo`: repository description. Optional. | String |
| **private** | For `create_remote_repo`: boolean visibility control. Default: `true`. GitHub read responses also include `visibility` with `public`, `internal`, or `private`. | Boolean |
### **`file`**
**Parameters**
| **Name** | **Definition** | **Format** |
| - | - | :-: |
| **action** | File operation. Values: `read`, `read_multiple`, `write`, `write_multiple`, `delete`, `list`, `find`, `search`, `copy`, `move`, `commit`, etc. | String (required) |
| **repo\_id** | Repository identifier where files are located. | String (required) |
| **branch\_name** | Explicit WIP branch name when browsing a managed repo worktree. For managed GitHub repos, `file(action="read")` uses this ref to read from origin when the checkout has a remote; when omitted on the managed base checkout, Genesis reads the managed default branch from origin instead of a shared local clone. When the checkout has no git remote, Genesis reads the local tree and may include `freshness_notice`. | String |
| **file\_path** | Relative path to file in repository (no leading /). | String |
| **content** | File content. For text, pass the text directly. For binary (zip, image, parquet, sqlite, etc.), pass the base64 string here and set `is_base64=true` so it is decoded before writing. | String |
| **is\_base64** | For `action="write"`: when `true`, `content` is base64-decoded to the original bytes before writing (use this for binary files). For `action="write_multiple"`: ignored at the top level — set `is_base64` inside each `files[]` item instead. Ignored by all other actions. Default: `false`. | Boolean |
| **files** | Bulk files array. For `write`/`write_multiple`: `[{path, content, is_base64}]` (`content` is required). For `read_multiple`: path strings like `["a.sql"]` or objects like `[{"path": "a.sql"}]`. `repo_id` is required for `read_multiple`. | Array |
| **pattern** | Glob pattern for find/search operations (e.g., `*.py`, `**/*.md`). | String |
| **source\_patterns** | List of repo-relative glob patterns or exact file paths for bulk copy/move/delete operations. | Array of Strings |
| **target\_path** | Destination directory for copy/move operations. | String |
| **preserve\_structure** | When copying or moving files, preserve nested paths under the matched pattern scope. Default: `true`. With `source_patterns=["src/**/*"]`, `src/sub/file.txt` becomes `target/sub/file.txt`; with `source_patterns=["src/file.txt"]`, the parent directory is stripped so the result is `target/file.txt`. Set to `false` to flatten files into `target_path`. | Boolean |
| **message** | Commit message (for commit action). | String |
Use **repo\_id** consistently across git\_action and file operations to work within the same repository context. List available repos with `git_action(action="list_repos")`.
**Transferring existing files.** When the source already lives in a repository,
use `file(action="copy")` or `file(action="move")` for byte-exact server-side
transfer — never read a file and write the same bytes back. For inline or
generated binary content that is not already on disk, write base64 with
`is_base64=true`. Without `is_base64=true`, the base64 string is written as
literal ASCII text and the file is corrupt. For `write_multiple`, set
`is_base64` inside each `files[]` item rather than at the top level. See
[Git Action Tools](/docs/Genbot-Toolkit/Git-Action-Tools) for examples.
With `git_action(action="list_repos", details=True)`, Genesis always returns
`has_remote` as `true` or `false` so agents can filter cleanly. When a remote
exists, `remote_url` is credentials-redacted and `clone_source` is set when
Genesis can infer `github`, `gitlab`, `bitbucket`, or `azure_devops`. Use
`include_paths=True` to add `path` to each detail row.
`file(action="read")` supports partial and targeted reads with `start_line`,
`end_line`, `max_lines`, `start_byte`, `max_bytes`, `end_byte`,
`tail_bytes`, `max_chars`, `search_pattern`, `context_lines_before`,
`context_lines_after`, `max_matches`, `return_line_numbers`, `encoding`,
`force_text`, and `return_base64`. `file(action="read_multiple")` forwards
the same controls per file entry. When the target is a managed GitHub repo
base checkout, Genesis reads remote truth instead of the shared local clone
when the checkout has a git remote. Pass `branch_name` to read that ref on
origin; omit it to read the managed default branch. When the checkout has no
git remote, Genesis reads the local tree and includes `freshness_notice` (see
[Git Action Tools](/docs/Genbot-Toolkit/Git-Action-Tools)). On the
origin-backed remote-read path, `start_line`, `end_line`,
`max_lines`, and `return_base64` are supported, but `search_pattern`,
`context_lines_before`, `context_lines_after`, `max_matches`, `start_byte`,
`end_byte`, `max_bytes`, `tail_bytes`, `max_chars`, `return_line_numbers`,
`force_text`, and `encoding` return an explicit error. Binary content on the
remote-read path must use `return_base64=true`.
Extremely large single-file reads follow the same guardrail as `git_action`: when `git_action(action="read_file")`, `file(action="read")`, or `file(action="inspect_structured_data")` exceeds the file-read inline budget (default `262,144` bytes / 256 KB, configurable with `GENESIS_TOOL_OUTPUT_FILE_READ_BUDGET`), Genesis returns `tool_output_capped`, `preview`, `truncation_info`, `full_output_ref`, and `agent_guidance`. When `full_output_ref` is not `null`, the full text is saved under `truncated_tool_outputs//...` in the `apps` BotGit repo and can be paged back with `file(action="read", file_path=full_output_ref, repo_id="apps", start_byte=0, max_bytes=N)`, continuing from each response's `continuation.next_start_byte`. The byte range is the shape that returns the saved copy exactly as written; the whole-file and line-window paths read in text mode and rewrite line endings.
## **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:
```python theme={null}
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:
```python theme={null}
# 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"
)
```
Add `branch_name="release/2026.05"` to clone and check out a non-default
branch in one call. Unless you override them, `shallow` and
`single_branch` both default to `true`; set `depth=0` for full history.
3. **Step 3: Manage Files**
Create, read, and organize files within the repository:
```python theme={null}
# 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:
```python theme={null}
git_action(
action="commit",
repo_id="my_data_project",
commit_message="Add customer data dictionary and initial ETL scripts"
)
```
`git_action(action="commit")` also accepts optional `co_authors`, for
example `["Jane Doe "]`, to append explicit
`Co-authored-by:` trailers without changing the primary commit author.
5. **Step 5: Create Pull Request**
Collaborate with team through pull requests:
```python theme={null}
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:
```python theme={null}
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.
Never commit sensitive credentials, API keys, or passwords to GitHub repositories. Use environment variables or secret management systems instead.
## **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**
✅ **clone\_repo** - Clone repository from GitHub URL\
✅ **create\_repo** - Create new local repository\
✅ **list\_repos** - Show all available repositories\
✅ **commit** - Commit staged changes\
✅ **push** - Push commits to remote\
✅ **pull** - Pull changes from remote\
✅ **create\_branch** - Create new branch\
✅ **switch\_branch** - Switch to different branch\
✅ **get\_status** - Show repository status\
✅ **get\_history** - View commit history\
✅ **create\_pull\_request** - Create PR on GitHub\
✅ **merge\_pull\_request** - Merge PR\
✅ **store\_github\_credentials** - Save authentication\
✅ **list\_remote\_repos** - List repos on GitHub\
✅ **check\_remote\_repo\_exists** - Check whether a GitHub repository already exists\
✅ **create\_remote\_repo** - Create a GitHub repository in a personal account or organization\
✅ **READ\_FILE** - Read a single file from a named GitHub branch, or the repo default branch when `branch` is omitted, through the GitHub Contents API\
✅ **file operations** - Full CRUD on repository files, including batch reads with `file(action="read_multiple")`
For GitHub remote repository responses, use `visibility` instead of
`private` when describing access to users. GitHub sets `private=true` for
both `internal` and `private` repositories, while `visibility` preserves the
full `public` / `internal` / `private` distinction.
Direct `READ_FILE` requires `repo_name`, `owner`, and `file_path`. `branch`
is optional; when omitted, Genesis reads the repo default branch and falls
back to `main` if the default branch is unavailable. `connection` is
optional; when omitted, Genesis uses the caller's effective scoped default
GitHub connection (My default, then Role default). See
[Default connection layers](/docs/Setup/Connections#default-connection-layers).
Successful responses include `content`, `text`, `text_is_lossy`, `sha`,
`size`, `encoding`, `ref`, `path`, and `source`.
When a scoped GitHub default resolves but its saved credentials are missing
or invalid (for example an empty PAT or failed GitHub App token mint), Genesis
returns an error instead of silently falling back to the `GITHUB_TOKEN`
environment variable. Genesis uses `GITHUB_TOKEN` only when **no** scoped
default applies for the caller.
### **Not Supported**
❌ Git submodules or subtrees\
❌ Git LFS (Large File Storage) direct management\
❌ GitHub Issues or Projects management\
❌ Repository webhooks configuration\
❌ GitHub Pages deployment\
❌ Repository transfer or ownership changes\
❌ Advanced merge strategies (squash, rebase from tool)
To execute GitHub Actions workflows, use [CI Pipeline Tools](/docs/Genbot-Toolkit/CI-Pipeline-Tools).
### **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](/docs/Setup/Connections).
* **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**
Make small, focused commits with clear messages. Easier to review, revert, and understand history.
Use feature branches for development. Keep main/master stable and deployable.
Always pull latest changes before pushing to avoid conflicts and ensure smooth integration.
Write descriptive commit messages explaining what and why, not just what changed.
## **Example: Complete Data Project Workflow**
```python theme={null}
# 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**
Copy multiple files matching patterns:
```python theme={null}
file(
action="copy",
repo_id="customer_analytics",
source_patterns=["*.sql", "*.py"],
target_path="archive/",
preserve_structure=True
)
```
Copy or move a repo-relative exact file path into a directory:
```python theme={null}
file(
action="copy",
repo_id="customer_analytics",
source_patterns=["reports/monthly/summary.md"],
target_path="archive/",
preserve_structure=True
)
# Writes archive/summary.md
```
`preserve_structure` defaults to `true` for `file(action="copy")` and `file(action="move")`. Glob patterns preserve the path below the matched parent scope. Exact file paths use their parent directory as the matched scope, so `source_patterns=["reports/monthly/summary.md"]` writes `archive/summary.md` instead of recreating `archive/reports/monthly/summary.md`.
Read multiple repository files in one call:
```python theme={null}
file(
action="read_multiple",
repo_id="customer_analytics",
files=[
"ddl/customers.sql",
{"path": "ddl/orders.sql"},
"models/product_dim.sql",
]
)
```
`file(action="read_multiple")` accepts a recommended maximum of 20 files per call and a hard limit of 100. Total returned content is capped at 200 KB; when that limit is reached, remaining files are reported in `skipped`, `skipped_preview`, and `files_skipped`, and the top-level response adds `continuation_hint`. Large files are automatically truncated to about 20 KB. Successful reads include per-file `content` and `size`; truncated entries are marked with `truncated: true` and can also include `truncation_info`, `continuation`, `encoding`, `file_type`, `total_size`, `returned_size`, `returned_lines`, `total_lines`, `start_line`, `end_line`, `start_byte`, and `end_byte`. If any entry is truncated, the batch response adds a warning explaining how to continue from the correct byte or line offset, and the top-level response includes `files_truncated` with the count of truncated files. Use `file(action="read")` for binary or Excel files.
Very large `list`, `find`, and `unzip` responses are previewed instead of returned in full. `files` and `extracted_files` previews are trimmed to the first `50` paths, and `download_links` previews are trimmed to the first `20` links. Use fields such as `files_preview`, `files_truncated`, `files_omitted_count`, `total_files`, `files_continuation_hint`, `note`, and `narrowing_hint` to narrow `list` or `find` queries, or `extracted_files_preview` and `download_links_preview` to inspect the extracted directory.
### **Search Across Files**
Find specific content in repository:
```python theme={null}
file(
action="search",
repo_id="customer_analytics",
pattern="SELECT.*FROM customers",
regex=True
)
```
When `git_action(action="search")`, `git_action(action="grep")`, `file(action="search")`, or `file(action="fast_search")` returns zero matches for a repo on a non-default branch, the response can include `_branch_warning` with `current_branch`, `default_branch`, and `message`. Follow `_branch_warning.message` to switch to the default branch, run `git_action(action="pull")`, and retry the search.
### **Fetch Deep History**
Get more commit history for analysis:
```python theme={null}
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**
Discover accessible GitHub repositories across your personal account and, by
default, your organizations:
```python theme={null}
git_action(
action="list_remote_repos",
include_orgs=True
)
```
`include_orgs` is optional and defaults to `true`. Each repo in the
response includes both `private` and `visibility`. Use `visibility` when
reporting GitHub access levels because `private=true` covers both
`internal` and `private` repositories. The `summary` object also includes
`visibility_breakdown`, which counts repositories by visibility.
## **Troubleshooting**
* Verify Personal Access Token is valid and not expired
* Check token has required scopes: `repo`, `workflow`
* Re-store credentials with `store_github_credentials`
* Pull latest changes first: `git_action(action="pull")`
* Check for merge conflicts in `get_status`
* Verify you have write permissions to repository
* Verify file\_path uses forward slashes (/)
* Check path is relative without leading slash
* Use `file(action="list")` to see available files
* Switch to existing branch instead of creating
* Use `get_branch` to check current branch
* Delete old branch or use different name