# Github Composio Integration

> This skill should be used when the user wants to perform any GitHub operation (create repos, commit/push files, manage issues, pull requests, branches, releases, or read repository content) through the Composio MCP connection. It covers the full GitHub toolkit available via Composio, including connection management, tool discovery, and execution patterns. Use it whenever a GitHub task must be done without local git/gh CLI, relying instead on the connected Composio GitHub account.

- Skill: `eosbot/github-composio-integration` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add eosbot/github-composio-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eosbot/github-composio-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: EosBot (https://skillmd.com/u/eosbot)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/eosbot/github-composio-integration

---


# GitHub Integration via Composio MCP

## Overview

This skill enables complete GitHub automation through the Composio MCP connection already configured in this environment. It replaces the need for a local `git` client or the `gh` CLI by routing every GitHub operation through Composio's hosted GitHub toolkit. The connection is authenticated once (OAuth) and stays active; all operations use the `COMPOSIO_*` meta-tools exposed by the local MCP proxy at `http://localhost:8787/mcp`.

## Prerequisites

- The Composio MCP proxy must be running and reachable at `http://localhost:8787/mcp` (see `.mcp/composio/start.sh`).
- The GitHub toolkit connection must be `ACTIVE`. Verify with `COMPOSIO_MANAGE_CONNECTIONS` (`action: "status"`, `toolkits: ["github"]`). If not active, initiate with `action: "initiate"` and open the returned `redirectUrl` / `link` to authenticate.
- All GitHub tools are executed through `COMPOSIO_MULTI_EXECUTE_TOOL` using `tool_slug` (not `tool`) inside the `tools` array.

## Core Execution Pattern

Every GitHub action follows the same shape:

```
COMPOSIO_MULTI_EXECUTE_TOOL
  tools: [
    { tool_slug: "GITHUB_<ACTION>", arguments: { ... } }
  ]
```

Key conventions discovered and required:
- The meta-tool parameter is `tools` (array). Each element uses `tool_slug`, never `tool`.
- `COMPOSIO_SEARCH_TOOLS` and `COMPOSIO_GET_TOOL_SCHEMAS` are **meta-tools called directly** (not wrapped in `COMPOSIO_MULTI_EXECUTE_TOOL`).
- `COMPOSIO_SEARCH_TOOLS` expects `{ toolkit: "github", queries: [{ use_case: "..." }] }` — `queries` is an array of objects with a `use_case` string.
- `COMPOSIO_GET_TOOL_SCHEMAS` expects `{ tool_slugs: ["GITHUB_..."] }`.

## Connection Management

### Check status
```
COMPOSIO_MANAGE_CONNECTIONS { action: "status", toolkits: ["github"] }
```
Returns `has_active_connection: true/false` and `connected_account_id`.

### Initiate / reconnect
```
COMPOSIO_MANAGE_CONNECTIONS { action: "initiate", toolkits: ["github"] }
```
Returns a `link` (e.g. `https://connect.composio.dev/link/...`). Open it, authenticate with GitHub, then re-check status.

## Tool Discovery

Before executing an unknown action, discover the exact slug and schema:
```
COMPOSIO_SEARCH_TOOLS { toolkit: "github", queries: [{ use_case: "create a pull request" }] }
COMPOSIO_GET_TOOL_SCHEMAS { tool_slugs: ["GITHUB_CREATE_A_PULL_REQUEST"] }
```
The search response includes `recommended_plan_steps` (ordered execution plan) and `known_pitfalls` — follow them to avoid 401/403/404 and schema errors.

## Workflows

### 1. Create a repository
```
GITHUB_CREATE_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER
  name: <repo-name>            (required)
  private: false
  description: "..."
  auto_init: true              (creates initial README + main branch)
  license_template: "mit"
  gitignore_template: "Node"
```
After creation, the repo is available at `https://github.com/<authenticated-user>/<name>`.

### 2. Commit / push multiple files (atomic)
Use `GITHUB_COMMIT_MULTIPLE_FILES` — it uses Git Data APIs to avoid SHA conflicts on parallel edits.
```
GITHUB_COMMIT_MULTIPLE_FILES
  owner: <username|org>        (required)
  repo: <repo-name>            (required)
  branch: "main"               (required)
  message: "..."               (required)
  upserts: [ { path: "README.md", content: "..." }, ... ]   (required for creates/updates)
  deletes: [ "old/file.txt" ]  (optional)
  base_branch: "main"          (required ONLY when branch does not exist yet)
  author: { name: "...", email: "..." }   (optional)
```
Pitfall: when committing to a new branch (e.g. `feature/x`), always set `base_branch` to the existing base (`main`/`master`). Omit `base_branch` if the branch already exists.

### 3. Read repository content
```
GITHUB_GET_REPOSITORY_CONTENT
  owner: <owner>   (required)
  repo: <repo>     (required)
  path: ""         (required; "" lists root, "src" lists dir)
  ref: "main"      (optional; defaults to default branch)
```
Directories return an entry list; files return `content` (sometimes base64-encoded — decode when `encoding: "base64"`).

### 4. Create an issue
```
GITHUB_CREATE_AN_ISSUE
  owner: <owner>   (required)
  repo: <repo>     (required)
  title: "..."     (required)
  body: "..."
  labels: ["bug"]
  assignees: ["user"]
```

### 5. Create a pull request
```
GITHUB_CREATE_A_PULL_REQUEST
  owner: <owner>   (required)
  repo: <repo>     (required)
  head: "feature/x"  (required; source branch)
  base: "main"      (required; target branch)
  title: "..."
  body: "..."
  draft: false
```

### 6. Create repo from template
```
GITHUB_CREATE_A_REPOSITORY_USING_A_TEMPLATE
  template_owner: <owner>   (required)
  template_repo: <repo>     (required)
  name: <new-repo>          (required)
  private: false
  include_all_branches: false
```

## Known Pitfalls

- **401**: invalid/missing credentials → re-initiate connection.
- **403**: missing OAuth scopes or org policy → check granted scopes during auth.
- **404** on `GET_A_REPOSITORY`/`GET_REPOSITORY_CONTENT`: treat as permission/visibility signal, not definitive absence.
- **`COMPOSIO_SEARCH_TOOLS` inside `MULTI_EXECUTE`**: fails — call it directly.
- **`tool` vs `tool_slug`**: `MULTI_EXECUTE_TOOL` requires `tool_slug`.
- **Large directory listings** (800+ items): Composio may return `data_preview` instead of full `content` — the `structure_info.data_structure.properties.content.length` field still reports the true count.
- **`GITHUB_COMMIT_MULTIPLE_FILES` with `files`**: wrong key — use `upserts`.

## Quick Reference

| Action | Required args |
|--------|-------------|
| CREATE_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER | name |
| COMMIT_MULTIPLE_FILES | owner, repo, branch, message, upserts[] |
| GET_REPOSITORY_CONTENT | owner, repo, path |
| CREATE_AN_ISSUE | owner, repo, title |
| CREATE_A_PULL_REQUEST | owner, repo, head, base |
| CREATE_A_REPOSITORY_USING_A_TEMPLATE | template_owner, template_repo, name |

For the full, current schema of any tool, run `COMPOSIO_GET_TOOL_SCHEMAS` with the target `tool_slugs`.

## Reference Files

- `references/github-tool-schemas.json` — Complete input schemas (required fields, properties, descriptions) for the six core GitHub tools documented above. Load this file when an exact parameter shape is needed before execution.