GitHub

Overview

GitHub is the world’s largest code hosting platform, offering Git-based version control, issue tracking, pull request reviews, and continuous integration. With the GitHub integration in SquadOS, your agents can create and manage repositories, open issues, review and merge pull requests, publish releases, and search code — all programmatically, without leaving the platform.

• Official website: https://github.com/
• Composio documentation: docs.composio.dev/toolkits/github

Authentication

This tool uses OAuth 2.0 (OAUTH2) to connect.

You will need the following fields:

Field	Required	Description
oauth_token	Yes	OAuth 2.0 access token obtained by authorizing access to your GitHub account through the Composio connection page.

How to get credentials

1. Go to the Composio connection page (see “How to connect in SquadOS” below) and click Connect.
2. You will be redirected to GitHub to authorize access. Log in if needed.
3. Review the requested permissions and click Authorize.
4. The OAuth token is generated and stored automatically by Composio — you do not need to copy it manually.

Tip

Use a GitHub account with the permissions needed for the repositories your agents will access. For private repositories in an organization, make sure OAuth access has been approved by the organization administrator under Settings → OAuth Apps.

How to connect in SquadOS

1. Go to Tools in the side menu (/admin/tools).
2. Open the Available tab and search for GitHub.
3. Click the card to open the details and hit Connect.
4. You’re taken to the secure connection page hosted by Composio, where you authorize access via OAuth to GitHub.
5. Once done, you’re sent back to SquadOS with the account connected and the tool available to agents. (Connection-flow details in Organization Tools.)

Available actions

Note

This integration exposes 867 actions in total. The most relevant ones are listed below; see the full list in the Composio documentation.

Create an issue

GITHUB_CREATE_AN_ISSUE

Creates a new issue in a GitHub repository, requiring the repository to exist and have issues enabled; specific fields like assignees, milestone, or labels may require push access.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The GitHub account owner of the repository (case-insensitive).
repo	string	Yes	The name of the repository, without the .git extension (case-insensitive).
title	string	Yes	The title for the new issue.
body	string	No	The detailed textual contents of the new issue.
labels	array	No	Array of label names to associate with this issue. Only users with push access can set labels; they are silently dropped otherwise.
assignees	array	No	GitHub login names for users to assign to this issue. Only users with push access can set assignees.
milestone	string	No	The ID of the milestone to associate this issue with (e.g., "5"). Only users with push access can set the milestone.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get an issue

GITHUB_GET_AN_ISSUE

Retrieves detailed information about a specific issue in a repository using the owner, repository name, and issue number.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Username of the account owning the repository. Not case-sensitive.
repo	string	Yes	Name of the repository (without .git extension). Not case-sensitive.
issue_number	integer	Yes	The identifying number of the issue.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

List repository issues

GITHUB_LIST_REPOSITORY_ISSUES

Lists issues (including pull requests) from a GitHub repository. Requires BOTH owner AND repo parameters.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The GitHub account owner (user or organization) of the repository. Not case-sensitive.
repo	string	Yes	The name of the repository (without .git extension). Not case-sensitive.
state	string	No	Filters issues by state: "open", "closed", or "all".
labels	string	No	A comma-separated list of label names to filter by (e.g., "bug,ui").
assignee	string	No	Filter by assignee username. Use "none" for unassigned or "*" for any.
sort	string	No	Sort field: "created", "updated", or "comments".
since	string	No	Only issues updated at or after this ISO 8601 timestamp.
per_page	integer	No	Number of results per page (max 100).
page	integer	No	Page number for results.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Create an issue comment

GITHUB_CREATE_AN_ISSUE_COMMENT

Creates a new comment on an existing GitHub issue or pull request within the specified repository.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Account owner of the repository (username or organization); not case-sensitive.
repo	string	Yes	Name of the repository (without .git extension); not case-sensitive.
issue_number	integer	Yes	Number identifying the issue or pull request for the comment.
body	string	Yes	Comment content in GitHub Flavored Markdown.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Add labels to an issue

GITHUB_ADD_LABELS_TO_AN_ISSUE

Adds labels (provided in the request body) to a repository issue; labels that do not already exist are created.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Username or organization name owning the repository (case-insensitive).
repo	string	Yes	Repository name, without the .git extension (case-insensitive).
issue_number	integer	Yes	Positive integer that uniquely identifies the issue within the repository. Must be >= 1.
labels	array	Yes	Array of label names to add to the issue. Labels that don’t exist will be created automatically.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Create a pull request

GITHUB_CREATE_A_PULL_REQUEST

Creates a pull request in a GitHub repository, requiring existing base and head branches; title or issue must be provided.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The account owner of the repository. Not case-sensitive.
repo	string	Yes	The name of the repository, without the .git extension. Not case-sensitive.
head	string	Yes	The name of the branch where your changes are implemented. This branch must already exist. For cross-repository PRs, use username:branch.
base	string	Yes	The name of the branch you want the changes pulled into. Must be an existing branch on the target repository.
title	string	No	The title of the new pull request. Required unless issue is specified.
body	string	No	The detailed description or contents of the pull request.
draft	boolean	No	If true, creates the pull request as a draft. Draft PRs cannot be merged until marked as ready for review.
issue	integer	No	The number of an existing issue to convert into a pull request. Required if title is not specified.
maintainer_can_modify	boolean	No	Indicates whether maintainers of the upstream repository can modify the pull request.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get a pull request

GITHUB_GET_A_PULL_REQUEST

Retrieves a specific pull request from a GitHub repository using its owner, repository name, and pull request number.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The username of the account that owns the repository. Not case-sensitive.
repo	string	Yes	The name of the repository, without the .git extension. Not case-sensitive.
pull_number	integer	Yes	The number that identifies the specific pull request.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Merge a pull request

GITHUB_MERGE_A_PULL_REQUEST

Merges an open and mergeable pull request in a repository. A 405 error can occur if the PR is still a draft, branch protection rules are not satisfied, or the base branch has been modified since the PR was last synced.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Repository owner’s username. Not case-sensitive.
repo	string	Yes	Repository name, without the .git extension. Not case-sensitive.
pull_number	integer	Yes	The unique number identifying the pull request. The PR must be open, not a draft, and all branch protection rules must be satisfied.
merge_method	string	No	Merge strategy: "merge", "squash", or "rebase". Defaults to repository’s setting.
commit_title	string	No	Title for the merge commit message.
commit_message	string	No	Additional details for the merge commit message.
sha	string	No	SHA of the pull request’s head commit. Must match for merge to succeed.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

List pull requests

GITHUB_LIST_PULL_REQUESTS

Lists pull requests for a GitHub repository. The owner and repo parameters are REQUIRED.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The GitHub username or organization name that owns the repository.
repo	string	Yes	The name of the repository (without the .git extension).
state	string	No	Filter by pull request state: "open", "closed", or "all".
head	string	No	Filter by head user/org and branch name, e.g., user:ref-name.
base	string	No	Filter by base branch name.
sort	string	No	Sort results by: "created", "updated", "popularity", or "long-running".
direction	string	No	Sort direction: "asc" or "desc".
per_page	integer	No	Number of results per page (maximum 100).
page	integer	No	Page number for results.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Create a review for a pull request

GITHUB_CREATE_A_REVIEW_FOR_A_PULL_REQUEST

Creates a pull request review, allowing approval, change requests, or comments; body is required if event is REQUEST_CHANGES or COMMENT, and omitting event makes the review PENDING.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Username of the account owning the repository (case-insensitive).
repo	string	Yes	Repository name, without the .git extension (case-insensitive).
pull_number	integer	Yes	Identifying number of the pull request.
event	string	No	Review action type: "APPROVE", "REQUEST_CHANGES", or "COMMENT". If omitted, review is PENDING.
body	string	No	Review’s main body text; required if event is REQUEST_CHANGES or COMMENT.
comments	array	No	Inline draft review comments. Each object requires path (relative file path) and body (comment text), with optional line and side for diff location.
commit_id	string	No	SHA of the commit to review; defaults to the latest pull request commit.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get a repository

GITHUB_GET_A_REPOSITORY

Retrieves detailed information about an existing and accessible GitHub repository.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The username of the account that owns the repository. Case-insensitive.
repo	string	Yes	The name of the repository, without the .git extension. Case-insensitive.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Create a repository for the authenticated user

GITHUB_CREATE_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER

Creates a new repository for the authenticated user, optionally within an organization if team_id is specified.

Input parameters

Name	Type	Required	Description
name	string	Yes	The name of the repository. Must be unique within your account. Can only contain alphanumeric characters, hyphens, underscores, and periods.
description	string	No	A short description of the repository.
private	boolean	No	Whether the repository is private (true) or public (false).
auto_init	boolean	No	Whether to initialize the repository with a README.
license_template	string	No	SPDX license key identifier (lowercase), e.g., "mit", "apache-2.0".
gitignore_template	string	No	Desired .gitignore template, e.g., "Python", "Node".
has_issues	boolean	No	Whether issues are enabled.
has_wiki	boolean	No	Whether the wiki is enabled.
has_discussions	boolean	No	Whether discussions are enabled.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Create a fork

GITHUB_CREATE_A_FORK

Creates a fork of an accessible repository, optionally into a specific organization, with a new name, or copying only the default branch.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The username or organization name that owns the repository. Not case-sensitive.
repo	string	Yes	The name of the repository, without the .git extension. Not case-sensitive.
organization	string	No	The GitHub organization name to fork the repository into. If not specified, the fork is created in the authenticated user’s account.
name	string	No	The desired name for the newly created fork. If not provided, uses the original repository name.
default_branch_only	boolean	No	If True, only the default branch is copied.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get a branch

GITHUB_GET_A_BRANCH

Retrieves detailed information for a specified branch within a GitHub repository.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The account owner of the repository. Not case-sensitive.
repo	string	Yes	The name of the repository without the .git extension. Not case-sensitive.
branch	string	Yes	The name of the branch. Cannot contain wildcard characters. If "HEAD" is provided, it resolves to the repository’s default branch.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

List branches

GITHUB_LIST_BRANCHES

Lists branches for an existing GitHub repository, with an option to filter by protection status.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Account owner’s username (case-insensitive).
repo	string	Yes	Repository name, excluding .git extension (case-insensitive).
protected	boolean	No	Filter by protection status: true for protected, false for unprotected; omit for all branches.
per_page	integer	No	Number of results per page (max 100).
page	integer	No	Page number for paginated results.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

List commits

GITHUB_LIST_COMMITS

Lists commits for a GitHub repository. Optionally filter by SHA/branch, path, author, committer, or date range.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The account owner of the repository (username or organization name).
repo	string	Yes	The name of the repository without the .git extension.
sha	string	No	SHA hash or branch name to start listing commits from. Defaults to the repository’s default branch.
path	string	No	Only commits modifying this specific file path will be returned.
author	string	No	Filter commits by the commit author’s GitHub login or email address.
committer	string	No	Filter commits by the commit committer’s GitHub login or email address.
since	string	No	Only commits created on or after this ISO 8601 timestamp.
until	string	No	Only commits created before this ISO 8601 timestamp.
per_page	integer	No	Number of results to return per page (max 100).
page	integer	No	Page number of the results to fetch.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get a commit

GITHUB_GET_A_COMMIT

Retrieves a specific commit from a repository by its owner, name, and a valid commit reference (SHA, branch, or tag), supporting pagination for large diffs.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The username or organization name that owns the repository. Not case-sensitive.
repo	string	Yes	The name of the repository, without the .git extension. Not case-sensitive.
ref	string	Yes	The commit reference: a SHA, branch name (e.g., heads/main), or tag name (e.g., tags/v1.0).
page	integer	No	Page number for paginating the commit’s diff if it’s too large.
per_page	integer	No	Number of results per page when paginating the commit’s diff (max 100).

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Create or update file contents

GITHUB_CREATE_OR_UPDATE_FILE_CONTENTS

Creates a new file or updates an existing file in a GitHub repository; SHA can be provided to validate file updates, automatically fetched if not provided.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The account owner of the repository (not case-sensitive).
repo	string	Yes	The name of the repository (not case-sensitive, without the .git extension).
path	string	Yes	The full path to the file in the repository, including filename and extension. Do not include leading slashes.
message	string	Yes	The commit message for this file creation or update.
content	string	Yes	The new file content. Can be provided as plain text (auto-encoded to Base64) or already Base64-encoded.
branch	string	No	The branch name. Defaults to the repository’s default branch if omitted.
sha	string	No	The blob SHA of the file being replaced. Automatically fetched if not provided.
author__name	string	No	Author’s name. If specified, author__email is also required.
author__email	string	No	Author’s email. If specified, author__name is also required.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get repository content

GITHUB_GET_REPOSITORY_CONTENT

Retrieves a file’s Base64 encoded content or lists a directory’s contents from a GitHub repository.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Required. The account owner of the repository. Not case-sensitive.
repo	string	Yes	Required. The name of the repository, without the .git extension. Not case-sensitive.
path	string	Yes	Path to file or directory in the repository. Empty string ("") retrieves root directory contents. Do NOT pass branch names here — use the ref parameter instead.
ref	string	No	The name of the commit, branch, or tag to read from. Defaults to the repository’s default branch.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Create a release

GITHUB_CREATE_A_RELEASE

Creates a release in a GitHub repository for a specified tag; the tag must be unique for published releases.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The account owner of the repository (username or organization name). Not case-sensitive.
repo	string	Yes	The name of the repository, without the .git extension. Not case-sensitive.
tag_name	string	Yes	The name of the tag for this release. Must be unique for published releases.
name	string	No	The title of the release. Defaults to tag_name if omitted.
body	string	No	A detailed description of the release. Markdown formatting is supported.
draft	boolean	No	Set to true to create an unpublished (draft) release. Defaults to false.
prerelease	boolean	No	Set to true to identify this release as a pre-release. Defaults to false.
generate_release_notes	boolean	No	Set to true to automatically generate the title and description from the commit history since the last release.
target_commitish	string	No	The commitish value from which the Git tag is created. Defaults to the repository’s default branch.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Get a release

GITHUB_GET_A_RELEASE

Gets a specific release from a GitHub repository, provided the repository is accessible and the release exists.

Input parameters

Name	Type	Required	Description
owner	string	Yes	The username of the account that owns the repository. Not case-sensitive.
repo	string	Yes	The name of the repository, without the .git extension. Not case-sensitive.
release_id	integer	Yes	The unique numerical identifier for the release.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Search repositories

GITHUB_SEARCH_REPOSITORIES

Searches GitHub repositories using a flexible query (keywords, qualifiers) with sorting, ordering, and pagination. The q parameter is REQUIRED.

Input parameters

Name	Type	Required	Description
q	string	Yes	REQUIRED non-empty search query. Qualifiers: language:LANG, stars:N, forks:N, topic:TOPIC, license:LICENSE, user:USERNAME, org:ORGNAME, is:public|private, archived:true|false. Max 5 AND/OR/NOT operators.
sort	string	No	Field to sort results by: "stars", "forks", "help-wanted-issues", "updated", or "created".
order	string	No	Sort order: "desc" (default) or "asc". Effective only when sort is specified.
per_page	integer	No	Number of repository results per page (max 100). Defaults to 30.
page	integer	No	Page number for results. Defaults to 1.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Search code

GITHUB_SEARCH_CODE

Searches code file contents and paths on the default branch of GitHub repositories using a query string; searches only files under 384 KB, returns max 1000 results by best match.

Input parameters

Name	Type	Required	Description
q	string	Yes	Code search query, including keywords and qualifiers (e.g., language:python, user:octocat, repo:owner/repo).
per_page	integer	No	Results per page (max 100).
page	integer	No	Page number for results.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Search issues and pull requests

GITHUB_SEARCH_ISSUES_AND_PULL_REQUESTS

Searches GitHub for issues and pull requests. Supports keywords, qualifiers (repo:, org:, state:, label:, author:, assignee:, etc.), and type filters (is:issue, is:pr). The @me shorthand is automatically resolved to your username.

Input parameters

Name	Type	Required	Description
q	string	Yes	Search query using GitHub’s search syntax. Type filters (is:issue, is:pr) cannot be used alone — they must be combined with at least one keyword or other qualifier. Max 5 AND/OR/NOT operators.
sort	string	No	Field for sorting results: "comments", "reactions", "created", "updated", and others.
order	string	No	Order for sorted results: "asc" or "desc". Effective only when sort is provided.
per_page	integer	No	Number of results per page.
page	integer	No	Page number for results.
response_detail	string	No	Level of detail: "minimal" (default, optimized for AI agents) or "full" (complete GitHub API response).

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Star a specified repository

GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER

Stars a specified repository for the authenticated user; this action is idempotent and succeeds even if the repository is already starred.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Required. The username of the account that owns the repository. Not case-sensitive.
repo	string	Yes	Required. The name of the repository, without the .git extension. Not case-sensitive.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.

Commit Multiple Files

GITHUB_COMMIT_MULTIPLE_FILES

Tool to atomically create, update, or delete multiple files in a GitHub repository as a single commit. Uses Git Data APIs to avoid SHA mismatch conflicts that occur with the Contents API when multiple files are modified in parallel. When committing to a new branch, you MUST provide base_branch.

Input parameters

Name	Type	Required	Description
owner	string	Yes	Repository owner (username or organization name).
repo	string	Yes	Repository name (without .git extension).
branch	string	Yes	Target branch name to commit to. If this branch doesn’t exist, you MUST provide base_branch.
message	string	Yes	Commit message describing the changes.
upserts	array	No	List of files to create or update. Each entry requires path, content, and optional encoding (utf-8 or base64).
deletes	array	No	List of file paths to delete from the repository. Files must exist in the repository.
base_branch	string	No	REQUIRED when committing to a new branch that doesn’t exist yet. Specifies the existing branch to create the new branch from (e.g., "main").
author	object	No	Git author information.
committer	object	No	Git committer information.
force	boolean	No	Force update the branch reference. WARNING: Use with caution as this can overwrite commits.
max_retries	integer	No	Maximum number of retries when encountering race conditions (422 ‘not a fast forward’ errors). Set to 0 to disable retries.

Output

Name	Type	Required	Description
data	string	Yes	Data from the action execution.
error	string	No	Error message if execution failed.
successful	boolean	Yes	Whether the action executed successfully.