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"}