Skip to main content

Actions

The ballerinax/github package exposes the following clients:

ClientPurpose
ClientProvides access to the GitHub REST API (903 resource functions) for managing repositories, issues, pull requests, organizations, users, and more.

Client

Provides access to the GitHub REST API (903 resource functions) for managing repositories, issues, pull requests, organizations, users, and more.

Configuration

FieldTypeDefaultDescription
authhttp:BearerTokenConfigRequiredAuthentication configuration. Supply a Personal Access Token (PAT) as a bearer token: {token: "<PAT>"}.
httpVersionhttp:HttpVersionHTTP_2_0HTTP protocol version used by the client.
http1Settingshttp:ClientHttp1Settings()HTTP/1.x protocol settings including keep-alive and chunking behavior.
http2Settingshttp:ClientHttp2Settings()HTTP/2 protocol settings.
timeoutdecimal60Request timeout in seconds before the connection is closed.
forwardedstring"disable"Controls whether to set forwarded or x-forwarded headers.
poolConfighttp:PoolConfiguration()Connection pool configuration for request pooling.
cachehttp:CacheConfig()HTTP caching configuration.
compressionhttp:CompressionCOMPRESSION_AUTOCompression handling for accept-encoding headers.
circuitBreakerhttp:CircuitBreakerConfig()Circuit breaker configuration for fault tolerance.
retryConfighttp:RetryConfig()Retry configuration for failed requests.
responseLimitshttp:ResponseLimitConfigs()Inbound response size limits.
secureSockethttp:ClientSecureSocket()SSL/TLS configuration.
proxyhttp:ProxyConfig()Proxy server configuration.
validationbooleantrueWhen enabled, validates response payloads against declared schemas using the constraint package.

Initializing the client

import ballerinax/github;

configurable string authToken = ?;

github:Client github = check new ({
auth: {
token: authToken
}
});

Operations

Repository management

List repositories for the authenticated user

Lists repositories for the authenticated user.

Parameters:

NameTypeRequiredDescription
visibility"all"|"public"|"private"NoFilter by repository visibility.
'type"all"|"owner"|"public"|"private"|"member"|()NoFilter by repository type.
sort"created"|"updated"|"pushed"|"full_name"NoSort field for results.
per_pageintNoNumber of results per page (max 100).

Returns: github:Repository[]|error

Sample code:

github:Repository[] repos = check github->/user/repos(visibility = "private", 'type = ());

Sample response:

[{"id": 123456, "name": "my-project", "full_name": "octocat/my-project", "private": true, "description": "A sample project", "html_url": "https://github.com/octocat/my-project", "default_branch": "main"}]
Create a repository for the authenticated user

Creates a new repository for the authenticated user.

Parameters:

NameTypeRequiredDescription
payloadgithub:User_repos_bodyYesRepository creation payload including name, description, and visibility.

Returns: github:Repository|error

Sample code:

github:Repository createdRepo = check github->/user/repos.post({
name: "new-project",
'private: true,
description: "My new project"
});

Sample response:

{"id": 789012, "name": "new-project", "full_name": "octocat/new-project", "private": true, "description": "My new project", "default_branch": "main"}
Get a repository

Retrieves details of a specific repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: github:FullRepository|error

Sample code:

github:FullRepository repo = check github->/repos/["octocat"]/["Hello-World"];

Sample response:

{"id": 1296269, "name": "Hello-World", "full_name": "octocat/Hello-World", "private": false, "description": "This your first repo!", "stargazers_count": 80, "forks_count": 9, "default_branch": "master"}
Update a repository

Updates a repository's settings.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
payloadgithub:Repos_bodyYesRepository update payload.

Returns: github:FullRepository|error

Sample code:

github:FullRepository updated = check github->/repos/["octocat"]/["Hello-World"].patch({
description: "Updated description",
has_issues: true
});

Sample response:

{"id": 1296269, "name": "Hello-World", "full_name": "octocat/Hello-World", "description": "Updated description", "has_issues": true}
Delete a repository

Deletes a repository. Requires admin access.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: error?

Sample code:

check github->/repos/["octocat"]/["old-project"].delete();
Create a fork

Creates a fork of a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
payloadgithub:Repo_forks_bodyYesFork creation payload with optional organization and name.

Returns: github:FullRepository|error

Sample code:

github:FullRepository fork = check github->/repos/["octocat"]/["Hello-World"]/forks.post({});

Sample response:

{"id": 999999, "name": "Hello-World", "full_name": "myuser/Hello-World", "fork": true, "parent": {"full_name": "octocat/Hello-World"}}
Get all repository topics

Lists all repository topics.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: github:Topic|error

Sample code:

github:Topic topics = check github->/repos/["octocat"]/["Hello-World"]/topics;

Sample response:

{"names": ["ballerina", "integration", "github-api"]}
Replace all repository topics

Replaces all repository topics.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
payloadgithub:Repo_topics_bodyYesPayload with the new list of topic names.

Returns: github:Topic|error

Sample code:

github:Topic updated = check github->/repos/["octocat"]/["Hello-World"]/topics.put({
names: ["ballerina", "integration"]
});

Sample response:

{"names": ["ballerina", "integration"]}

Issue management

List repository issues

Lists issues in a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
state"open"|"closed"|"all"NoFilter by issue state.
labelsstringNoComma-separated list of label names to filter by.
sort"created"|"updated"|"comments"NoSort field.
per_pageintNoNumber of results per page (max 100).

Returns: github:Issue[]|error

Sample code:

github:Issue[] issues = check github->/repos/["octocat"]/["Hello-World"]/issues(state = "open");

Sample response:

[{"id": 1, "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": {"login": "octocat"}, "labels": [{"name": "bug"}]}]
Create an issue

Creates an issue in a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
payloadgithub:Repo_issues_bodyYesIssue creation payload with title, body, labels, and assignees.

Returns: github:Issue|error

Sample code:

github:Issue issue = check github->/repos/["octocat"]/["Hello-World"]/issues.post({
title: "Found a bug",
body: "I'm having a problem with this.",
labels: ["bug"]
});

Sample response:

{"id": 1, "number": 1348, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "labels": [{"name": "bug"}], "html_url": "https://github.com/octocat/Hello-World/issues/1348"}
Get an issue

Retrieves a specific issue by number.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
issue_numberintYesThe number of the issue.

Returns: github:Issue|error

Sample code:

github:Issue issue = check github->/repos/["octocat"]/["Hello-World"]/issues/[1347];

Sample response:

{"id": 1, "number": 1347, "state": "open", "title": "Found a bug", "body": "I'm having a problem with this.", "user": {"login": "octocat"}}
Update an issue

Updates an existing issue.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
issue_numberintYesThe number of the issue.
payloadgithub:Issues_issue_number_bodyYesIssue update payload.

Returns: github:Issue|error

Sample code:

github:Issue updated = check github->/repos/["octocat"]/["Hello-World"]/issues/[1348].patch({
state: "closed",
labels: ["bug", "wontfix"]
});

Sample response:

{"id": 1, "number": 1348, "state": "closed", "title": "Found a bug", "labels": [{"name": "bug"}, {"name": "wontfix"}]}
List issue comments

Lists comments on an issue.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
issue_numberintYesThe number of the issue.
per_pageintNoNumber of results per page (max 100).

Returns: github:IssueComment[]|error

Sample code:

github:IssueComment[] comments = check github->/repos/["octocat"]/["Hello-World"]/issues/[1347]/comments();

Sample response:

[{"id": 10001, "body": "This has been fixed.", "user": {"login": "contributor1"}, "created_at": "2024-01-15T10:30:00Z"}]
Create an issue comment

Creates a comment on an issue.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
issue_numberintYesThe number of the issue.
payloadgithub:Issue_number_comments_bodyYesComment payload containing the body text.

Returns: github:IssueComment|error

Sample code:

github:IssueComment comment = check github->/repos/["octocat"]/["Hello-World"]/issues/[1348]/comments.post({
body: "This has been fixed in the latest release."
});

Sample response:

{"id": 10002, "body": "This has been fixed in the latest release.", "user": {"login": "octocat"}, "created_at": "2024-01-15T10:30:00Z"}
List labels for an issue

Lists labels on an issue.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
issue_numberintYesThe number of the issue.

Returns: github:Label[]|error

Sample code:

github:Label[] labels = check github->/repos/["octocat"]/["Hello-World"]/issues/[1347]/labels;

Sample response:

[{"id": 208045946, "name": "bug", "color": "f29513", "description": "Something isn't working"}]
Add labels to an issue

Adds labels to an issue.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
issue_numberintYesThe number of the issue.
payloadgithub:Issue_number_labels_bodyYesPayload with label names to add.

Returns: github:Label[]|error

Sample code:

github:Label[] labels = check github->/repos/["octocat"]/["Hello-World"]/issues/[1347]/labels.post({
labels: ["enhancement", "help wanted"]
});

Sample response:

[{"id": 208045946, "name": "bug", "color": "f29513"}, {"id": 208045947, "name": "enhancement", "color": "84b6eb"}, {"id": 208045948, "name": "help wanted", "color": "128A0C"}]
List milestones

Lists milestones for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
state"open"|"closed"|"all"NoFilter by milestone state.

Returns: github:Milestone[]|error

Sample code:

github:Milestone[] milestones = check github->/repos/["octocat"]/["Hello-World"]/milestones(state = "open");

Sample response:

[{"id": 1, "number": 1, "title": "v1.0", "state": "open", "open_issues": 4, "closed_issues": 8}]
Create a milestone

Creates a milestone.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
payloadgithub:Repo_milestones_bodyYesMilestone creation payload with title and optional due date.

Returns: github:Milestone|error

Sample code:

github:Milestone milestone = check github->/repos/["octocat"]/["Hello-World"]/milestones.post({
title: "v2.0",
due_on: "2025-06-01T00:00:00Z"
});

Sample response:

{"id": 2, "number": 2, "title": "v2.0", "state": "open", "due_on": "2025-06-01T00:00:00Z"}

Pull request management

List pull requests

Lists pull requests in a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
state"open"|"closed"|"all"NoFilter by pull request state.
headstringNoFilter by head user or head user and branch name (user:ref-name).
basestringNoFilter by base branch name.
per_pageintNoNumber of results per page (max 100).

Returns: github:PullRequestSimple[]|error

Sample code:

github:PullRequestSimple[] prs = check github->/repos/["octocat"]/["Hello-World"]/pulls(state = "open");

Sample response:

[{"id": 1, "number": 42, "state": "open", "title": "Add new feature", "user": {"login": "octocat"}, "head": {"ref": "feature-branch"}, "base": {"ref": "main"}}]
Create a pull request

Creates a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
payloadgithub:Repo_pulls_bodyYesPull request creation payload with title, head, base, and body.

Returns: github:PullRequest|error

Sample code:

github:PullRequest pr = check github->/repos/["octocat"]/["Hello-World"]/pulls.post({
title: "Amazing new feature",
head: "feature-branch",
base: "main",
body: "Please review and merge this feature."
});

Sample response:

{"id": 1, "number": 43, "state": "open", "title": "Amazing new feature", "html_url": "https://github.com/octocat/Hello-World/pull/43", "head": {"ref": "feature-branch"}, "base": {"ref": "main"}}
Get a pull request

Retrieves a specific pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.

Returns: github:PullRequest|error

Sample code:

github:PullRequest pr = check github->/repos/["octocat"]/["Hello-World"]/pulls/[42];

Sample response:

{"id": 1, "number": 42, "state": "open", "title": "Add new feature", "mergeable": true, "commits": 3, "additions": 100, "deletions": 20}
Update a pull request

Updates a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.
payloadgithub:Pulls_pull_number_bodyYesPull request update payload.

Returns: github:PullRequest|error

Sample code:

github:PullRequest updated = check github->/repos/["octocat"]/["Hello-World"]/pulls/[43].patch({
title: "Updated feature title",
body: "Updated description for the PR."
});

Sample response:

{"id": 1, "number": 43, "state": "open", "title": "Updated feature title", "body": "Updated description for the PR."}
Merge a pull request

Merges a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.
payloadgithub:Pull_number_merge_bodyYesMerge payload with optional commit title and merge method.

Returns: github:PullRequestMergeResult|error

Sample code:

github:PullRequestMergeResult result = check github->/repos/["octocat"]/["Hello-World"]/pulls/[43]/merge.put({
commit_title: "Merge feature branch",
merge_method: "squash"
});

Sample response:

{"sha": "abc123def456", "merged": true, "message": "Pull Request successfully merged"}
List reviews for a pull request

Lists reviews on a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.

Returns: github:PullRequestReview[]|error

Sample code:

github:PullRequestReview[] reviews = check github->/repos/["octocat"]/["Hello-World"]/pulls/[42]/reviews;

Sample response:

[{"id": 80, "user": {"login": "reviewer1"}, "body": "Looks good!", "state": "APPROVED"}]
Create a review for a pull request

Creates a review on a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.
payloadgithub:Pull_number_reviews_bodyYesReview payload with body and event (APPROVE, REQUEST_CHANGES, COMMENT).

Returns: github:PullRequestReview|error

Sample code:

github:PullRequestReview review = check github->/repos/["octocat"]/["Hello-World"]/pulls/[43]/reviews.post({
body: "Looks good! Ship it.",
event: "APPROVE"
});

Sample response:

{"id": 80, "user": {"login": "octocat"}, "body": "Looks good! Ship it.", "state": "APPROVED"}
Request reviewers for a pull request

Requests reviewers for a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.
payloadgithub:Pull_number_requested_reviewers_bodyYesPayload with reviewer usernames or team slugs.

Returns: github:PullRequestSimple|error

Sample code:

github:PullRequestSimple pr = check github->/repos/["octocat"]/["Hello-World"]/pulls/[43]/requested_reviewers.post({
reviewers: ["reviewer1", "reviewer2"]
});

Sample response:

{"id": 1, "number": 43, "requested_reviewers": [{"login": "reviewer1"}, {"login": "reviewer2"}]}
List commits on a pull request

Lists commits on a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.

Returns: github:Commit[]|error

Sample code:

github:Commit[] commits = check github->/repos/["octocat"]/["Hello-World"]/pulls/[42]/commits;

Sample response:

[{"sha": "abc123", "commit": {"message": "Initial implementation", "author": {"name": "octocat", "date": "2024-01-10T10:00:00Z"}}}]
List pull request files

Lists files changed in a pull request.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pull_numberintYesThe number of the pull request.

Returns: github:DiffEntry[]|error

Sample code:

github:DiffEntry[] files = check github->/repos/["octocat"]/["Hello-World"]/pulls/[42]/files;

Sample response:

[{"sha": "abc123", "filename": "src/main.bal", "status": "modified", "additions": 50, "deletions": 10, "changes": 60}]

Branch & commit management

List branches

Lists branches for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
per_pageintNoNumber of results per page (max 100).

Returns: github:ShortBranch[]|error

Sample code:

github:ShortBranch[] branches = check github->/repos/["octocat"]/["Hello-World"]/branches();

Sample response:

[{"name": "main", "commit": {"sha": "abc123"}, "protected": true}, {"name": "feature-branch", "commit": {"sha": "def456"}, "protected": false}]
Get a branch

Retrieves a specific branch.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
branchstringYesThe branch name.

Returns: github:BranchWithProtection|error

Sample code:

github:BranchWithProtection branch = check github->/repos/["octocat"]/["Hello-World"]/branches/["main"];

Sample response:

{"name": "main", "commit": {"sha": "abc123", "commit": {"message": "Latest commit"}}, "protected": true}
List commits

Lists commits on a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
shastringNoSHA or branch to start listing commits from.
pathstringNoOnly include commits containing this file path.
per_pageintNoNumber of results per page (max 100).

Returns: github:Commit[]|error

Sample code:

github:Commit[] commits = check github->/repos/["octocat"]/["Hello-World"]/commits(sha = "main");

Sample response:

[{"sha": "abc123", "commit": {"message": "Update README", "author": {"name": "octocat", "date": "2024-01-10T10:00:00Z"}}, "author": {"login": "octocat"}}]
Get a commit

Retrieves a specific commit by SHA or ref.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
refstringYesThe commit SHA, branch name, or tag name.

Returns: github:Commit|error

Sample code:

github:Commit commit = check github->/repos/["octocat"]/["Hello-World"]/commits/["abc123"];

Sample response:

{"sha": "abc123", "commit": {"message": "Update README", "tree": {"sha": "def456"}}, "stats": {"additions": 10, "deletions": 2, "total": 12}}

Release & tag management

List releases

Lists releases for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
per_pageintNoNumber of results per page (max 100).

Returns: github:Release[]|error

Sample code:

github:Release[] releases = check github->/repos/["octocat"]/["Hello-World"]/releases();

Sample response:

[{"id": 1, "tag_name": "v1.0.0", "name": "Release v1.0.0", "draft": false, "prerelease": false, "published_at": "2024-01-01T00:00:00Z"}]
Create a release

Creates a release.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
payloadgithub:Repo_releases_bodyYesRelease creation payload with tag name, name, and body.

Returns: github:Release|error

Sample code:

github:Release release = check github->/repos/["octocat"]/["Hello-World"]/releases.post({
tag_name: "v2.0.0",
name: "Release v2.0.0",
body: "Major release with new features.",
draft: false,
prerelease: false
});

Sample response:

{"id": 2, "tag_name": "v2.0.0", "name": "Release v2.0.0", "body": "Major release with new features.", "draft": false, "prerelease": false, "html_url": "https://github.com/octocat/Hello-World/releases/tag/v2.0.0"}
Get a release

Retrieves a specific release.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
release_idintYesThe release ID.

Returns: github:Release|error

Sample code:

github:Release release = check github->/repos/["octocat"]/["Hello-World"]/releases/[1];

Sample response:

{"id": 1, "tag_name": "v1.0.0", "name": "Release v1.0.0", "body": "Initial release", "assets": []}
Update a release

Updates a release.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
release_idintYesThe release ID.
payloadgithub:Releases_release_id_bodyYesRelease update payload.

Returns: github:Release|error

Sample code:

github:Release updated = check github->/repos/["octocat"]/["Hello-World"]/releases/[1].patch({
body: "Updated release notes with fixes."
});

Sample response:

{"id": 1, "tag_name": "v1.0.0", "name": "Release v1.0.0", "body": "Updated release notes with fixes."}
Delete a release

Deletes a release.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
release_idintYesThe release ID.

Returns: error?

Sample code:

check github->/repos/["octocat"]/["Hello-World"]/releases/[1].delete();
Get the latest release

Retrieves the latest release for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: github:Release|error

Sample code:

github:Release latest = check github->/repos/["octocat"]/["Hello-World"]/releases/latest;

Sample response:

{"id": 2, "tag_name": "v2.0.0", "name": "Release v2.0.0", "published_at": "2024-06-01T00:00:00Z"}
List repository tags

Lists tags for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
per_pageintNoNumber of results per page (max 100).

Returns: github:Tag[]|error

Sample code:

github:Tag[] tags = check github->/repos/["octocat"]/["Hello-World"]/tags();

Sample response:

[{"name": "v2.0.0", "commit": {"sha": "abc123"}}, {"name": "v1.0.0", "commit": {"sha": "def456"}}]

Content & file operations

Get repository content

Gets the contents of a file or directory in a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pathstringYesThe file path within the repository.
refstringNoThe name of the commit/branch/tag. Defaults to the default branch.

Returns: github:ContentDirectory|github:ContentFile|github:ContentSubmodule|github:ContentSymlink|error

Sample code:

github:ContentFile|github:ContentDirectory|github:ContentSubmodule|github:ContentSymlink content = check github->/repos/["octocat"]/["Hello-World"]/contents/["README.md"];

Sample response:

{"type": "file", "encoding": "base64", "size": 442, "name": "README.md", "path": "README.md", "sha": "abc123", "content": "IyBIZWxsby1Xb3JsZA=="}
Create or update file contents

Creates or updates a file in a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pathstringYesThe file path within the repository.
payloadgithub:Content_path_bodyYesFile content payload with message, content (Base64), and optional SHA for updates.

Returns: github:FileCommit|error

Sample code:

github:FileCommit fileCommit = check github->/repos/["octocat"]/["Hello-World"]/contents/["docs/guide.md"].put({
message: "Add guide document",
content: "IyBHdWlkZQ=="
});

Sample response:

{"content": {"name": "guide.md", "path": "docs/guide.md", "sha": "def456"}, "commit": {"sha": "789abc", "message": "Add guide document"}}
Delete a file

Deletes a file from a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
pathstringYesThe file path within the repository.
payloadgithub:Content_path_body_2YesPayload with commit message and file SHA.

Returns: github:FileCommit|error

Sample code:

github:FileCommit result = check github->/repos/["octocat"]/["Hello-World"]/contents/["docs/old-guide.md"].delete({
message: "Remove outdated guide",
sha: "abc123"
});

Sample response:

{"content": null, "commit": {"sha": "def789", "message": "Remove outdated guide"}}
Get a repository README

Gets the README file for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: github:ContentFile|error

Sample code:

github:ContentFile readme = check github->/repos/["octocat"]/["Hello-World"]/readme;

Sample response:

{"type": "file", "name": "README.md", "path": "README.md", "size": 442, "encoding": "base64", "content": "IyBIZWxsby1Xb3JsZA=="}

Collaborator & organization management

List repository collaborators

Lists collaborators for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
per_pageintNoNumber of results per page (max 100).

Returns: github:Collaborator[]|error

Sample code:

github:Collaborator[] collaborators = check github->/repos/["octocat"]/["Hello-World"]/collaborators();

Sample response:

[{"login": "contributor1", "id": 100, "permissions": {"admin": false, "push": true, "pull": true}}]
Add a repository collaborator

Adds a collaborator to a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
usernamestringYesThe GitHub username of the collaborator to add.
payloadgithub:Collaborators_username_bodyNoOptional payload specifying permission level.

Returns: github:RepositoryInvitation|error?

Sample code:

github:RepositoryInvitation? invitation = check github->/repos/["octocat"]/["Hello-World"]/collaborators/["newuser"].put({
permission: "push"
});

Sample response:

{"id": 1, "repository": {"id": 1296269, "name": "Hello-World"}, "invitee": {"login": "newuser"}, "permissions": "write"}
Remove a repository collaborator

Removes a collaborator from a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
usernamestringYesThe GitHub username of the collaborator to remove.

Returns: error?

Sample code:

check github->/repos/["octocat"]/["Hello-World"]/collaborators/["olduser"].delete();
Get an organization

Retrieves an organization's profile.

Parameters:

NameTypeRequiredDescription
orgstringYesThe organization name.

Returns: github:OrganizationFull|error

Sample code:

github:OrganizationFull org = check github->/orgs/["ballerina-platform"];

Sample response:

{"login": "ballerina-platform", "id": 27461, "name": "Ballerina Platform", "description": "Cloud-native programming language", "public_repos": 150}
List organization repositories

Lists repositories for an organization.

Parameters:

NameTypeRequiredDescription
orgstringYesThe organization name.
'type"all"|"public"|"private"|"forks"|"sources"|"member"NoFilter by repository type.
per_pageintNoNumber of results per page (max 100).

Returns: github:MinimalRepository[]|error

Sample code:

github:MinimalRepository[] orgRepos = check github->/orgs/["ballerina-platform"]/repos('type = "public");

Sample response:

[{"id": 456789, "name": "ballerina-lang", "full_name": "ballerina-platform/ballerina-lang", "private": false, "description": "The Ballerina programming language"}]
List organization members

Lists members of an organization.

Parameters:

NameTypeRequiredDescription
orgstringYesThe organization name.
role"all"|"admin"|"member"NoFilter by member role.
per_pageintNoNumber of results per page (max 100).

Returns: github:SimpleUser[]|error

Sample code:

github:SimpleUser[] members = check github->/orgs/["ballerina-platform"]/members(role = "admin");

Sample response:

[{"login": "admin-user", "id": 1001, "avatar_url": "https://avatars.githubusercontent.com/u/1001"}]
List teams

Lists teams in an organization.

Parameters:

NameTypeRequiredDescription
orgstringYesThe organization name.
per_pageintNoNumber of results per page (max 100).

Returns: github:Team[]|error

Sample code:

github:Team[] teams = check github->/orgs/["ballerina-platform"]/teams();

Sample response:

[{"id": 1, "name": "core-team", "slug": "core-team", "description": "Core development team", "permission": "push"}]

User operations

Get the authenticated user

Retrieves the authenticated user's profile.

Returns: github:PrivateUser|github:PublicUser|error

Sample code:

github:PrivateUser|github:PublicUser user = check github->/user;

Sample response:

{"login": "octocat", "id": 1, "name": "The Octocat", "email": "[email protected]", "public_repos": 8, "followers": 20, "following": 0}
Get a user

Retrieves a public user's profile by username.

Parameters:

NameTypeRequiredDescription
usernamestringYesThe GitHub username.

Returns: github:PrivateUser|github:PublicUser|error

Sample code:

github:PrivateUser|github:PublicUser user = check github->/users/["octocat"];

Sample response:

{"login": "octocat", "id": 1, "name": "The Octocat", "company": "GitHub", "public_repos": 8, "followers": 20}
Star a repository for the authenticated user

Stars a repository for the authenticated user.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: error?

Sample code:

check github->/user/starred/["ballerina-platform"]/["ballerina-lang"].put();
Unstar a repository for the authenticated user

Unstars a repository for the authenticated user.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: error?

Sample code:

check github->/user/starred/["ballerina-platform"]/["ballerina-lang"].delete();
List followers of a user

Lists followers of a user.

Parameters:

NameTypeRequiredDescription
usernamestringYesThe GitHub username.
per_pageintNoNumber of results per page (max 100).

Returns: github:SimpleUser[]|error

Sample code:

github:SimpleUser[] followers = check github->/users/["octocat"]/followers();

Sample response:

[{"login": "fan1", "id": 2001}, {"login": "fan2", "id": 2002}]
List repositories for a user

Lists public repositories for a user.

Parameters:

NameTypeRequiredDescription
usernamestringYesThe GitHub username.
'type"all"|"owner"|"member"NoFilter by repository type.
per_pageintNoNumber of results per page (max 100).

Returns: github:MinimalRepository[]|error

Sample code:

github:MinimalRepository[] repos = check github->/users/["octocat"]/repos('type = "owner");

Sample response:

[{"id": 123456, "name": "Hello-World", "full_name": "octocat/Hello-World", "private": false}]

Gist management

List gists for the authenticated user

Lists gists for the authenticated user.

Parameters:

NameTypeRequiredDescription
per_pageintNoNumber of results per page (max 100).

Returns: github:BaseGist[]|error

Sample code:

github:BaseGist[] gists = check github->/gists();

Sample response:

[{"id": "aa5a315d61ae9438b18d", "description": "Hello World Example", "public": true, "files": {"hello.bal": {"filename": "hello.bal", "language": "Ballerina", "size": 42}}}]
Create a gist

Creates a gist.

Parameters:

NameTypeRequiredDescription
payloadgithub:Gists_bodyYesGist creation payload with description, files, and visibility.

Returns: github:GistSimple|error

Sample code:

github:GistSimple gist = check github->/gists.post({
description: "Hello World Example",
'public: true,
files: {"hello.bal": {content: "import ballerina/io;\npublic function main() {\n io:println(\"Hello\");\n}"}}
});

Sample response:

{"id": "aa5a315d61ae9438b18d", "description": "Hello World Example", "html_url": "https://gist.github.com/aa5a315d61ae9438b18d", "public": true}
Get a gist

Retrieves a specific gist.

Parameters:

NameTypeRequiredDescription
gist_idstringYesThe gist ID.

Returns: github:GistSimple|error

Sample code:

github:GistSimple gist = check github->/gists/["aa5a315d61ae9438b18d"];

Sample response:

{"id": "aa5a315d61ae9438b18d", "description": "Hello World Example", "files": {"hello.bal": {"filename": "hello.bal", "content": "import ballerina/io;\npublic function main() {\n    io:println(\"Hello\");\n}"}}}
Update a gist

Updates a gist.

Parameters:

NameTypeRequiredDescription
gist_idstringYesThe gist ID.
payloadgithub:Gists_gist_id_bodyYesGist update payload.

Returns: github:GistSimple|error

Sample code:

github:GistSimple updated = check github->/gists/["aa5a315d61ae9438b18d"].patch({
description: "Updated Hello World"
});

Sample response:

{"id": "aa5a315d61ae9438b18d", "description": "Updated Hello World"}
Delete a gist

Deletes a gist.

Parameters:

NameTypeRequiredDescription
gist_idstringYesThe gist ID.

Returns: error?

Sample code:

check github->/gists/["aa5a315d61ae9438b18d"].delete();
Star a gist

Stars a gist.

Parameters:

NameTypeRequiredDescription
gist_idstringYesThe gist ID.

Returns: error?

Sample code:

check github->/gists/["aa5a315d61ae9438b18d"]/star.put();
Fork a gist

Forks a gist.

Parameters:

NameTypeRequiredDescription
gist_idstringYesThe gist ID.

Returns: github:BaseGist|error

Sample code:

github:BaseGist forked = check github->/gists/["aa5a315d61ae9438b18d"]/forks.post();

Sample response:

{"id": "bb6b426e72bf549c29e", "description": "Hello World Example", "owner": {"login": "octocat"}}
Create a gist comment

Creates a comment on a gist.

Parameters:

NameTypeRequiredDescription
gist_idstringYesThe gist ID.
payloadgithub:Gist_id_comments_bodyYesComment payload with body text.

Returns: github:GistComment|error

Sample code:

github:GistComment comment = check github->/gists/["aa5a315d61ae9438b18d"]/comments.post({
body: "Nice example!"
});

Sample response:

{"id": 1, "body": "Nice example!", "user": {"login": "octocat"}, "created_at": "2024-01-15T10:30:00Z"}

Notification management

List notifications for the authenticated user

Lists notifications for the authenticated user.

Parameters:

NameTypeRequiredDescription
allbooleanNoIf true, show notifications marked as read.
participatingbooleanNoIf true, only show notifications where the user is directly participating.

Returns: github:Thread[]|error

Sample code:

github:Thread[] notifications = check github->/notifications(all = false);

Sample response:

[{"id": "1", "repository": {"full_name": "octocat/Hello-World"}, "subject": {"title": "New issue opened", "type": "Issue"}, "reason": "subscribed", "unread": true}]
Mark notifications as read

Marks all notifications as read.

Parameters:

NameTypeRequiredDescription
payloadgithub:Notifications_bodyYesPayload with optional last_read_at timestamp.

Returns: github:Notifications_response_202|error?

Sample code:

check github->/notifications.put({last_read_at: "2024-01-15T00:00:00Z"});
Get a thread

Retrieves a specific notification thread.

Parameters:

NameTypeRequiredDescription
thread_idintYesThe thread ID.

Returns: github:Thread|error

Sample code:

github:Thread thread = check github->/notifications/threads/[1];

Sample response:

{"id": "1", "repository": {"full_name": "octocat/Hello-World"}, "subject": {"title": "Bug report", "type": "Issue"}, "reason": "mention", "unread": true}
Mark a thread as read

Marks a notification thread as read.

Parameters:

NameTypeRequiredDescription
thread_idintYesThe thread ID.

Returns: error?

Sample code:

check github->/notifications/threads/[1].patch();

Security advisories

List global security advisories

Lists global security advisories.

Parameters:

NameTypeRequiredDescription
ghsa_idstringNoFilter by GHSA identifier.
'type"reviewed"|"malware"|"unreviewed"NoFilter by advisory type.
ecosystemstringNoFilter by package ecosystem (e.g., npm, pip, maven).
severity"unknown"|"low"|"medium"|"high"|"critical"NoFilter by severity level.
per_pageintNoNumber of results per page.

Returns: github:GlobalAdvisory[]|error

Sample code:

github:GlobalAdvisory[] advisories = check github->/advisories(severity = "critical", ecosystem = "npm");

Sample response:

[{"ghsa_id": "GHSA-xxxx-xxxx-xxxx", "cve_id": "CVE-2024-12345", "summary": "Critical vulnerability in example package", "severity": "critical", "published_at": "2024-01-10T00:00:00Z"}]
Get a global security advisory

Retrieves a specific global security advisory.

Parameters:

NameTypeRequiredDescription
ghsa_idstringYesThe GHSA identifier.

Returns: github:GlobalAdvisory|error

Sample code:

github:GlobalAdvisory advisory = check github->/advisories/["GHSA-xxxx-xxxx-xxxx"];

Sample response:

{"ghsa_id": "GHSA-xxxx-xxxx-xxxx", "cve_id": "CVE-2024-12345", "summary": "Critical vulnerability", "severity": "critical", "vulnerabilities": [{"package": {"ecosystem": "npm", "name": "example-pkg"}}]}

Actions & workflows

List repository workflows

Lists repository workflows.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.

Returns: github:Workflows_response|error

Sample code:

github:Workflows_response workflows = check github->/repos/["octocat"]/["Hello-World"]/actions/workflows;

Sample response:

{"total_count": 2, "workflows": [{"id": 1, "name": "CI", "state": "active", "path": ".github/workflows/ci.yml"}]}
List workflow runs for a repository

Lists workflow runs for a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
statusstringNoFilter by status (e.g., completed, in_progress, queued).

Returns: github:Workflow_runs_response|error

Sample code:

github:Workflow_runs_response runs = check github->/repos/["octocat"]/["Hello-World"]/actions/runs(status = "completed");

Sample response:

{"total_count": 1, "workflow_runs": [{"id": 100, "name": "CI", "status": "completed", "conclusion": "success", "head_branch": "main"}]}
Get a workflow run

Retrieves a specific workflow run.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
run_idintYesThe workflow run ID.

Returns: github:WorkflowRun|error

Sample code:

github:WorkflowRun run = check github->/repos/["octocat"]/["Hello-World"]/actions/runs/[100];

Sample response:

{"id": 100, "name": "CI", "status": "completed", "conclusion": "success", "head_branch": "main", "run_started_at": "2024-01-10T10:00:00Z"}
Cancel a workflow run

Cancels a workflow run.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
run_idintYesThe workflow run ID.

Returns: error?

Sample code:

check github->/repos/["octocat"]/["Hello-World"]/actions/runs/[100]/cancel.post();
Re-run a workflow

Re-runs a workflow run.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
run_idintYesThe workflow run ID.

Returns: error?

Sample code:

check github->/repos/["octocat"]/["Hello-World"]/actions/runs/[100]/rerun.post();
Create a workflow dispatch event

Creates a workflow dispatch event to manually trigger a workflow.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
workflow_idgithub:Workflow_idYesThe workflow ID or workflow file name (e.g., ci.yml).
payloadgithub:Workflow_id_dispatches_bodyYesDispatch payload with ref (branch) and optional inputs.

Returns: error?

Sample code:

check github->/repos/["octocat"]/["Hello-World"]/actions/workflows/["ci.yml"]/dispatches.post({
ref: "main"
});

Star & watch operations

List stargazers

Lists users who starred a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
per_pageintNoNumber of results per page (max 100).

Returns: github:SimpleUser[]|github:Stargazer[]|error

Sample code:

github:SimpleUser[]|github:Stargazer[] stargazers = check github->/repos/["octocat"]/["Hello-World"]/stargazers();

Sample response:

[{"login": "fan1", "id": 2001}, {"login": "fan2", "id": 2002}]
List watchers

Lists users watching a repository.

Parameters:

NameTypeRequiredDescription
ownerstringYesThe account owner of the repository.
repostringYesThe name of the repository.
per_pageintNoNumber of results per page (max 100).

Returns: github:SimpleUser[]|error

Sample code:

github:SimpleUser[] watchers = check github->/repos/["octocat"]/["Hello-World"]/subscribers();

Sample response:

[{"login": "watcher1", "id": 3001}]
Search repositories

Searches for repositories matching a query.

Parameters:

NameTypeRequiredDescription
qstringYesThe search query (e.g., ballerina language:ballerina).
sort"stars"|"forks"|"help-wanted-issues"|"updated"NoSort field.
per_pageintNoNumber of results per page (max 100).

Returns: github:Search_repositories_response|error

Sample code:

github:Search_repositories_response results = check github->/search/repositories(q = "ballerina language:ballerina", sort = "stars");

Sample response:

{"total_count": 25, "incomplete_results": false, "items": [{"id": 123, "full_name": "ballerina-platform/ballerina-lang", "stargazers_count": 3500}]}
Search issues and pull requests

Searches for issues and pull requests matching a query.

Parameters:

NameTypeRequiredDescription
qstringYesThe search query (e.g., bug repo:octocat/Hello-World is:open).
sort"comments"|"reactions"|"reactions-+1"|"reactions--1"|"interactions"|"created"|"updated"NoSort field.
per_pageintNoNumber of results per page (max 100).

Returns: github:Search_issues_and_pull_requests_response|error

Sample code:

github:Search_issues_and_pull_requests_response results = check github->/search/issues(q = "bug repo:octocat/Hello-World is:open");

Sample response:

{"total_count": 5, "items": [{"number": 1347, "title": "Found a bug", "state": "open", "labels": [{"name": "bug"}]}]}
Search code

Searches for code matching a query.

Parameters:

NameTypeRequiredDescription
qstringYesThe search query (e.g., main repo:octocat/Hello-World language:ballerina).
per_pageintNoNumber of results per page (max 100).

Returns: github:Search_code_response|error

Sample code:

github:Search_code_response results = check github->/search/code(q = "import ballerinax/kafka repo:octocat/Hello-World");

Sample response:

{"total_count": 2, "items": [{"name": "main.bal", "path": "src/main.bal", "repository": {"full_name": "octocat/Hello-World"}}]}
Search users

Searches for users matching a query.

Parameters:

NameTypeRequiredDescription
qstringYesThe search query (e.g., octocat type:user).
per_pageintNoNumber of results per page (max 100).

Returns: github:Search_users_response|error

Sample code:

github:Search_users_response results = check github->/search/users(q = "octocat type:user");

Sample response:

{"total_count": 1, "items": [{"login": "octocat", "id": 1, "type": "User"}]}

License & meta

Get all commonly used licenses

Lists commonly used open source licenses.

Returns: github:LicenseSimple[]|error

Sample code:

github:LicenseSimple[] licenses = check github->/licenses;

Sample response:

[{"key": "mit", "name": "MIT License", "spdx_id": "MIT"}, {"key": "apache-2.0", "name": "Apache License 2.0", "spdx_id": "Apache-2.0"}]
Get GitHub meta information

Returns meta information about GitHub's APIs.

Returns: github:ApiOverview|error

Sample code:

github:ApiOverview meta = check github->/meta;

Sample response:

{"verifiable_password_authentication": true, "ssh_key_fingerprints": {"SHA256_RSA": "nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8"}}
Get rate limit status for the authenticated user

Returns the current rate limit status for the authenticated user.

Returns: github:RateLimitOverview|error

Sample code:

github:RateLimitOverview rateLimit = check github->/rate_limit;

Sample response:

{"resources": {"core": {"limit": 5000, "remaining": 4999, "reset": 1700000000}}, "rate": {"limit": 5000, "remaining": 4999}}
Get emojis

Lists all available GitHub emojis.

Returns: json|error

Sample code:

json emojis = check github->/emojis;

Sample response:

{"+1": "https://github.githubassets.com/images/icons/emoji/unicode/1f44d.png", "100": "https://github.githubassets.com/images/icons/emoji/unicode/1f4af.png"}