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

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.