GitHub
This page provides information on how to connect to GitHub. It enables users to perform actions such as creating issues, updating releases, searching for repositories, and managing project workflows directly from Appsmith.
Connect GitHub
To connect to GitHub, you need to authenticate using OAuth 2.0 . This authentication provides secure access to repositories and GitHub features based on your account permissions.
- Log in to your GitHub account if not already logged in
- Review the requested permissions
- Click "Authorize" to grant Appsmith access to your GitHub account
The OAuth flow provides a seamless experience but requires you to have a browser session.
Query GitHub
The following section is a reference guide that provides a description of the available commands with their parameters to create GitHub queries.
Create Issue
Creates a new issue in a specified GitHub repository. This command allows you to define the issue title, description, and assignees, and returns the created issue's details including its number, URL, and creation timestamp.
Owner string
The owner's name identifies the account or organization that owns the repository. This is the username or organization name that appears in the repository URL.
To locate the owner:
- Look at the URL:
https://github.com/[OWNER]/[REPO]
- The owner is the segment between
github.com/
and the next forward slash
For personal repositories, this will be your GitHub username. For organization repositories, this will be the organization name.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository the issue will be created in. This must be the exact name of the repository as it appears on GitHub, including capitalization and special characters.
To locate the repository name:
- Look at the URL:
https://github.com/[OWNER]/[REPO]
- The repo name is the segment after the owner name
Examples:
For a typical project repository:
awesome-project
You must have appropriate permissions (at least Write access) to create issues in the specified repository.
Title string
The title provides a concise summary of the issue. It should clearly communicate the problem or feature request in a single line. A good title helps maintainers and contributors quickly understand what the issue is about.
Best practices for issue titles:
- Keep it under 50-60 characters
- Be specific about the problem or request
- Use imperative mood (e.g., "Fix", "Add", "Update")
- Avoid vague descriptions like "Bug" or "Problem"
Examples:
For a bug report:
Fix login form validation on Safari browsers
For a feature request:
Add dark mode support to dashboard components
The title is displayed in issue lists and notifications, so clarity is essential for effective project management.
Body string
The body contains detailed information about the issue. It supports GitHub Flavored Markdown for rich formatting, including headings, lists, code blocks, tables, and embedded images.
A well-structured issue body typically includes a description of the problem or feature, steps to reproduce (for bugs), expected vs. actual behavior, and environment information.
Example for a bug report:
The login form fails to validate email addresses properly on Safari browsers.
The body field is optional but recommended for providing context that helps maintainers understand and address the issue effectively.
Assignees array
This property specifies GitHub usernames of people who should be assigned to the issue. Assignees are responsible for addressing the issue and receive notifications about it.
Example with multiple assignees:
["johndoe", "janedoe"]
Example with a single assignee:
["techleader"]
If you leave this field empty, the issue will be created without any assignees. You can only assign users who have access to the repository.
Update Issue
Updates an existing issue in a specified GitHub repository. This command allows you to modify the issue's title, body, assignees, and state (open/closed). It returns the updated issue details including any changes made.
Owner string
The owner's name identifies the account or organization that owns the repository containing the issue you want to update.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository contains the issue you want to update. This must be the exact name of the repository as it appears on GitHub, including capitalization and special characters.
Examples:
For a typical project repository:
awesome-project
For repositories with special characters:
react-native-app
You must have appropriate permissions (at least Write access) to update issues in the specified repository.
Issue Number integer
The issue number is a unique identifier for the issue within the repository. Each issue in a repository has a sequential number that distinguishes it from other issues.
To find the issue number:
- Look at the issue URL:
https://github.com/[OWNER]/[REPO]/issues/[NUMBER]
- The issue number is the numeric value after "/issues/"
- Alternatively, look at the issue page where the number is displayed next to the title (e.g., "#42")
Examples:
For the first issue in a repository:
1
For a later issue:
42
If you provide an issue number that doesn't exist in the repository, GitHub will return a 404 error.
Title string
The title field allows you to update the issue's summary. Changing the title can help clarify the issue's purpose or reflect new information discovered during investigation.
Examples:
Updating a bug report title with more specific information:
Fix login validation on Safari and Firefox browsers
Updating a feature request title to narrow scope:
Add dark mode support to dashboard components (Phase 1)
If this field is omitted, the existing title will remain unchanged.
Body string
The body field allows you to update the detailed description of the issue. You can use this to add new information, clarify details, or document progress.
Example of appending an update to an existing issue:
After investigation, this issue affects Safari 15.4+ and Firefox 98+, but not Chrome.
If this field is omitted, the existing body will remain unchanged.
Assignees array
This property allows you to update the list of GitHub users assigned to the issue. You can add new assignees, remove existing ones, or completely replace the assignee list.
Example to replace all assignees:
["newassignee1", "newassignee2"]
Example to remove all assignees (assign to no one):
[]
If this field is omitted, the existing assignees will remain unchanged.
State string
The state property controls whether the issue is open or closed. Changing the state is essential for workflow management and tracking progress.
Valid values:
"open"
- Marks the issue as active and needing attention"closed"
- Marks the issue as resolved or no longer relevant
Example to close an issue:
closed
Example to reopen an issue:
open
If this field is omitted, the existing state will remain unchanged.
Get Issue By Number
Retrieves detailed information about a specific issue in a GitHub repository using its unique issue number. This command returns comprehensive data about the issue, including its title, body, state, assignees, labels, comments count, and timestamps.
Owner string
The owner's name identifies the account or organization that owns the repository containing the issue you want to retrieve.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository contains the issue you want to retrieve.
You must have at least Read access to the repository to retrieve issues. For private repositories, you must be authenticated with appropriate permissions.
Issue Number integer
The issue number is a unique identifier for the issue within the repository. Each issue in a repository has a sequential number that distinguishes it from other issues.
Examples:
For the first issue in a repository:
1
For a later issue:
42
If you provide an issue number that doesn't exist in the repository, GitHub will return a 404 error.
The response will include all issue details including title, description, state, assignees, labels, and timestamps.
Lock Issue
Restricts comments and interactions on an issue to prevent further discussion. This is useful for issues that have become off-topic, heated, or resolved in a way that requires no further input. When an issue is locked, only users with write access to the repository can add new comments.
Owner string
The owner's name identifies the account or organization that owns the repository containing the issue you want to lock.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository contains the issue you want to lock.
You must have at least write access to the repository to lock issues.
Issue Number integer
The issue number is a unique identifier for the issue within the repository that you want to lock.
Examples:
For a specific issue:
42
For another issue:
107
If you provide an issue number that doesn't exist in the repository, GitHub will return a 404 error.
Lock Reason string
The lock reason explains why the issue is being locked. This helps maintain transparency in the project's governance and moderation decisions.
Valid lock reasons:
"off-topic"
- Conversations that are not relevant to the project or repository"too heated"
- Conversations that are getting too heated or unproductive"resolved"
- Issues that have been resolved and require no further discussion"spam"
- Content identified as spam or unwanted promotional material
Example:
off-topic
If no lock reason is provided, the issue will still be locked, but no reason will be displayed publicly.
Search Issue
Searches for issues across GitHub repositories based on specified criteria. This command allows you to find issues matching keywords, labels, assignees, and other filters, returning a list of matching issues with their details.
Owner string
The owner's name identifies the account or organization that owns the repository to search within.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository to search for issues.
You must have at least Read access to the repository to search for issues.
Filter string
The filter parameter defines the search criteria using GitHub's search syntax. This allows you to combine multiple filters to find exactly the issues you're looking for.
Common search qualifiers:
is:issue
oris:pr
- Search for issues or pull requestsis:open
oris:closed
- Filter by statelabel:bug
- Filter by labelauthor:username
- Filter by issue creatorassignee:username
- Filter by assignee
Examples:
To find open bug issues:
is:issue is:open label:bug
To find issues assigned to a specific user:
is:issue assignee:johndoe
The search results include issues that match all the specified criteria.
Create Release
Creates a new release for a repository. Releases are deployable project iterations that include compiled files, binary packages, and release notes. This command allows you to create a release from a specific tag, add a title, description, and mark it as a pre-release or draft if needed.
Owner string
The owner's name identifies the account or organization that owns the repository where you want to create a release.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository you want to create a release for.
You must have at least write access to the repository to create releases.
Tag Name string
The tag name specifies the Git tag from which to create the release. Tags in Git mark specific points in a repository's history, typically used to mark version releases.
Examples:
For a major release:
v1.0.0
For a pre-release:
v2.0.0-beta.1
The tag name is required and must be unique within the repository.
Target Commitish string
The target commitish value specifies the commit, branch, or tag reference from which to create the release tag (if the tag doesn't exist yet). This determines what code snapshot the release will represent.
Examples:
For a specific commit:
a7d9f5c
For a branch:
feature-branch
If target commitish is not specified, GitHub creates the tag from the default branch (usually main
or master
).
Body string
The body contains the release notes that describe what's new, what's changed, and any breaking changes in this release. This field supports GitHub Flavored Markdown for rich formatting.
Example of release notes:
## What's New
- Dark Mode support
- Performance Improvements
- Bug fixes for login issues
Well-crafted release notes help users understand what changed and decide whether to upgrade.
Draft boolean
The draft parameter determines whether the release is published immediately or saved as a draft for further editing before publication.
Example to create a draft release:
true
Example to create a published release:
false
If this parameter is omitted, the default is false
(published release).
Prerelease boolean
The prerelease parameter indicates whether this release should be identified as a non-production ready release. Pre-releases are useful for beta testing, release candidates, and early access versions.
Example to mark as prerelease:
true
Example for stable release:
false
If this parameter is omitted, the default is false
(stable release).
Discussion Category Name string
If given, creates a discussion in the specified category linked to the release. Must match an existing category in the repository.
Example:
Announcements
This parameter is optional. If omitted, no discussion will be created.
Generate Release Notes boolean
Indicates if the release should auto-generate notes using the specified name and body.
Example to generate release notes:
true
Example to use only the provided body:
false
If this parameter is omitted, the default is false
(no auto-generated notes).
Update Release
Updates an existing release in a GitHub repository. This command allows you to modify a release's title, description, draft/published status, and prerelease status without creating a new release.
Owner string
The owner's name identifies the account or organization that owns the repository containing the release you want to update.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository contains the release you want to update.
You must have at least write access to the repository to update releases.
Release ID integer
The release ID is a unique identifier for the release you want to update. Unlike tags which can be moved, the release ID is a permanent identifier for a specific release.
Example:
53425892
The release ID is required and must correspond to an existing release in the repository.
Tag Name string
The tag name specifies the Git tag to be updated for the release.
Example:
v1.0.1
If this field is omitted, the existing tag name will remain unchanged.
Target Commitish string
The target commitish value specifies the commit, branch, or tag reference to update the release tag to point to.
Example:
hotfix-branch
If this field is omitted, the existing target commitish will remain unchanged.
Body string
The body parameter allows you to update the release notes. This is useful for correcting information, adding details about post-release fixes, or improving documentation.
Example of updated release notes:
## UPDATE
This release has been updated with additional bug fixes.
If this field is omitted, the existing release notes will remain unchanged.
Draft boolean
The draft parameter allows you to change the publication status of the release:
- Change from draft to published (
false
) - Change from published to draft (
true
)
Example to publish a draft release:
false
If this field is omitted, the existing draft status will remain unchanged.
Prerelease boolean
The prerelease parameter allows you to change whether the release is marked as a prerelease:
- Mark a stable release as prerelease (
true
) - Mark a prerelease as stable (
false
)
Example to mark as stable release:
false
If this field is omitted, the existing prerelease status will remain unchanged.
Discussion Category Name string
Updates or creates a discussion in the specified category linked to the release.
Example:
Releases
If this field is omitted, the existing discussion settings will remain unchanged.
Generate Release Notes boolean
Indicates if the release notes should be regenerated automatically.
Example:
true
If this field is omitted, no auto-generation of notes will occur.
Get Release By Id
Retrieves detailed information about a specific release in a GitHub repository using its unique release ID. This command returns comprehensive data about the release, including its tag name, body, assets, and timestamps.
Owner string
The owner's name identifies the account or organization that owns the repository containing the release you want to retrieve.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository contains the release you want to retrieve.
You must have at least Read access to the repository to retrieve releases.
Release ID integer
The release ID is a unique identifier for the release you want to retrieve.
Example:
53425892
The release ID is required and must correspond to an existing release in the repository.
Get Release By Tag Name
Retrieves detailed information about a specific release in a GitHub repository using its tag name. This command returns comprehensive data about the release, including its ID, body, assets, and timestamps.
Owner string
The owner's name identifies the account or organization that owns the repository containing the release you want to retrieve.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository contains the release you want to retrieve.
You must have at least Read access to the repository to retrieve releases.
Tag Name string
The tag name specifies the Git tag of the release you want to retrieve.
Example:
v1.0.0
The tag name is required and must correspond to an existing release tag in the repository.
Delete Release
Deletes a release from a GitHub repository. This command permanently removes the release and its associated data, but does not delete the Git tag associated with the release.
Owner string
The owner's name identifies the account or organization that owns the repository containing the release you want to delete.
Examples:
For a personal repository:
janedoe
For an organization repository:
appsmith
If the owner is incorrect or doesn't exist, GitHub will return a 404 error.
Repo string
The repository name specifies which GitHub repository contains the release you want to delete.
You must have at least write access to the repository to delete releases.
Release ID integer
The release ID is a unique identifier for the release you want to delete.
Example:
53425892
The release ID is required and must correspond to an existing release in the repository.
Custom Action
Performs a custom GitHub API request that isn't covered by the predefined commands. This allows for advanced operations and accessing additional GitHub API endpoints.
This command allows you to make custom API calls to GitHub endpoints not covered by the standard commands. You can specify the endpoint, method, and parameters to access additional GitHub functionality.
Example:
To get repository statistics:
GET /repos/{owner}/{repo}/stats/contributors
To create a repository webhook:
POST /repos/{owner}/{repo}/hooks
Custom actions require appropriate authentication and permissions for the endpoints being accessed.