# 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.
1. Log in to your GitHub account if not already logged in
2. Review the requested permissions
3. 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` or `is:pr` - Search for issues or pull requests
* `is:open` or `is:closed` - Filter by state
* `label:bug` - Filter by label
* `author:username` - Filter by issue creator
* `assignee: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.