GitHub

Procedures and concepts for the GitHub integration.

The following documentation is for GitHub v2.4.1 (BDK).

Overview

GitHub is the world's leading platform for version control and collaborative software development. This integration enables automated repository management, issue tracking, pull request operations, and code deployment workflows. Streamline your development processes and enhance team collaboration on code projects.

Prerequisites

1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

• GitHub

How to Add the Book(s)

1. Go to Books → All Books.

2. Search for the name of the book and click on it.

3. Click on Install or Add Connection to add the book to your agent.

4. If adding a connection, you'll be prompted for connectivity details.

Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

Connect using API Key

Connect to the GitHub API using an API key.

Label	Description	Type
API Key	The API key to be used for connecting	sensitive

Procedures

to compare (commits) in a repository source

Compare two refs (branches, tags, or commit SHAs) in a GitHub repository.

Returns the comparison status, commit counts, and the list of files that differ between the two refs.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
base	The base ref to compare (branch, tag, or SHA).	text	Yes	(no default)
head	The head ref to compare (branch, tag, or SHA).	text	Yes	(no default)

Output Concepts

Concept	Description	Type
commits	A comparison with status, ahead_by, behind_by, total_commits, files, and html_url.	github comparison

Examples

Compare two branches

compare commits in "kognitos/bdk-api" with
    the base is "main"
    the head is "develop"

to create a (pull request) in a repository source

Create a pull request for a specified GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
pull request	The details required to create a pull request. It includes the title, head, base, and body.	github pull request	Yes	(no default)

Output Concepts

Concept	Description	Type
pull request	The pull request just created.	github pull request

Examples

Create a pull request from a repository

create a json
use the above as the pull request
set the pull request's "head" to "feature-branch"
set the pull request's "base" to "main"
set the pull request's "title" to "This is the title"
set the pull request's "body" to "This is the body"
create the pull request in "kognitos/bdk-api"

to create an (issue) in a repository source

Create an issue for a specified GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
issue	The details required to create an issue. It includes the title, and can contain body.	github issue	Yes	(no default)

Output Concepts

Concept	Description	Type
issue	The issue just created.	github issue

Examples

Create an issue from a repository

the issue is '{"title": "This is the title", "body": "This is the body"}'
create an issue in "kognitos/bdk-api"

to get the (commit files) from a repository source

Get the files changed in a specific commit.

Returns the list of files modified, added, or removed in the specified commit, including the unified diff patch for each file.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
sha	The commit SHA.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
commit files	A list of file diffs with filename, status, additions, deletions, changes, and patch.	github file diff

Examples

Get the files changed in a commit

get the commit files from "kognitos/bdk-api" with
    the sha is "abc123def456"

to get the (commits) from a repository source

FILTER - CAPABLE

Get the commits from a GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
branch	The branch to fetch commits from. Defaults to 'main'.	text	No	main

Output Concepts

Concept	Description	Type
commits	A list of commits with details such as commit message, author, and date.	github commit

Examples

Retrieve the list of commits from the main branch of a repository

get some commits from "kognitos/bdk-api"

Retrieve the list of commits from a specific branch of a repository

get some commits from "kognitos/bdk-api" with
    the branch is "develop"

Retrieve the list of commits that were committed in the specified time period

convert "2024-08-13T15:00:00Z" to a datetime
use the above as the start date
convert "2024-08-20T15:00:00Z" to a datetime
use the above as the end date
get the list of commits from "kognitos/bdk-api" whose date committed is after the start date and whose date committed is before the end date

to get the (file contents) from a repository source

Get file or directory contents from a GitHub repository.

For files, returns the decoded text content along with metadata. Files larger than 1 MB may not include content. For directories, returns a list of entries with metadata but no content.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
path	The file or directory path within the repository.	text	Yes	(no default)
ref	The branch, tag, or commit SHA to read from. Defaults to the repository default branch.	text	No	(no default)

Output Concepts

Concept	Description	Type
file contents	A list of file content entries with name, path, sha, size, type, and optionally decoded content.	github file content

Examples

Retrieve the contents of a file from a repository

get the file contents from "kognitos/bdk-api" with
    the path is "README.md"

Retrieve the contents of a directory from a specific branch

get the file contents from "kognitos/bdk-api" with
    the path is "src"
    the ref is "feature/oncall-fix"

to get the (issues) from a repository source

Get the issues from a GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
state	The state of the issues to fetch. Defaults to 'open'.	noun	No	open

Output Concepts

Concept	Description	Type
issues	A list of issues with details such as title, description, and URL.	github issue

Examples

Retrieve the list of issues from a repository

get some issues from "kognitos/bdk-api"

Retrieve the list of closed issues from a repository

get some issues from "kognitos/bdk-api" with
    the state is closed

to get the (pull request files) from a repository source

Get the files changed in a pull request.

Returns the list of files modified, added, or removed in the specified pull request, including the unified diff patch for each file.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
number	The pull request number.	number	Yes	(no default)

Output Concepts

Concept	Description	Type
pull request files	A list of file diffs with filename, status, additions, deletions, changes, and patch.	github file diff

Examples

Get the files changed in a pull request

get the pull request files from "kognitos/bdk-api" with
    the number is 42

Get the next page of files changed in a pull request

get the pull request files from "kognitos/bdk-api" with
    the number is 42
    the offset is 50
    the limit is 50

to get the (pull request) from a repository source

Get a pull request from a GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
number	The number of the pull request to fetch.	number	Yes	(no default)

Output Concepts

Concept	Description	Type
pull request	A pull request with details such as title, description, and URL.	github pull request

Examples

Retrieve the list of open pull requests from a repository

get a pull request in "kognitos/bdk-api"
    the number is 1

to get the (pull requests) from a repository source

Get the pull requests from a GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
state	The state of the pull requests to fetch. Defaults to 'open'.	noun	No	open
sort	The sort criteria for pull requests. One of 'created', 'updated', 'popularity', or 'long-running'. When omitted the API defaults to 'created'.	noun	No	(no default)
direction	The sort direction, either 'asc' or 'desc'. When omitted the API default depends on sort: 'desc' for 'created' (or no sort), 'asc' for 'updated', 'popularity', and 'long-running'.	noun	No	(no default)

Output Concepts

Concept	Description	Type
pull requests	A list of pull requests with details such as title, description, and URL.	github pull request

Examples

Retrieve the list of pull requests from a repository

get some pull requests in "kognitos/bdk-api"

Retrieve the list of open pull requests from a repository

get some pull requests in "kognitos/bdk-api" with
    the state is open

Retrieve the most recently updated closed pull requests

get some pull requests in "kognitos/bumblebee" with
    the state is closed
    the sort is updated
    the direction is desc

Retrieve at most 10 recently updated pull requests

get some pull requests in "kognitos/bumblebee" with
    the sort is updated
    the direction is desc
    the limit is 10

to get the (repositories) from a source organization

Get the repositories from a GitHub organization.

Input Concepts

Concept	Description	Type	Required	Default Value
source organization	The source organization to fetch repositories from.	conceptual or text	Yes	(no default)

Output Concepts

Concept	Description	Type
repositories	A list of repositories with details such as repository name, description, and URL.	github repository

Examples

Retrieve the list of repositories from an organization

get some repositories from the source organization
    the source organization is "kognitos"

to get the (team) from a source organization

Get a team from a GitHub organization.

Input Concepts

Concept	Description	Type	Required	Default Value
source organization	The source organization to fetch team from.	conceptual or text	Yes	(no default)
slug	The slug of the team to fetch.	text	Yes	(no default)

Output Concepts

Concept	Description	Type
team	A team with details such as team name.	github team

Examples

Retrieve the team from an organization

get "integrations-team" from "kognitos"

to get the (teams) from a source organization

Get the teams from a GitHub organization.

Input Concepts

Concept	Description	Type	Required	Default Value
source organization	The source organization to fetch teams from.	conceptual or text	Yes	(no default)

Output Concepts

Concept	Description	Type
teams	A list of teams with details such as team name.	github team

Examples

Retrieve the list of teams from an organization

get some teams from "kognitos"

to get the (user) from a name

Get a user from GitHub.

Input Concepts

Concept	Description	Type	Required	Default Value
name	The name of the user to fetch.	conceptual or text	Yes	(no default)

Output Concepts

Concept	Description	Type
user	The user details such as name, login, and email.	github user

Examples

Retrieve the details of a user

get the user "octocat"

to request reviewers for a (pull request)

Request reviewers for a pull request in a specified GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
pull request	The pull request.	github pull request	Yes	(no default)
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	text	Yes	(no default)
user names	The list of reviewers to request.	text	Yes	(no default)
team names	The list of team reviewers to request. Defaults to None.	text	No	(no default)

Output Concepts

Concept	Description	Type
pull request	The pull request with the reviewers just requested.	github pull request

Examples

Request reviewers for a pull request to request reviewers for a github pull request the user names are "ignacio-kognitos", "other-user" the team names are "kognitos-team"

get a pull request in "kognitos/bdk-api" with
    the number is 1
use the above as the pull request
request user_names for the pull request
    the repository source is "kognitos/bdk-api"
    the user names are "ignacio-kognitos", "other-user"
    the team names are "kognitos-team"

to search (code) in a repository source

Search code in a GitHub repository.

Searches for code matching the given query within the specified repository. Note that the GitHub code search API has a rate limit of 10 requests per minute.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
query	The search keywords to look for in the code.	text	Yes	(no default)
path	Optional path filter to restrict search to a directory.	text	No	(no default)
extension	Optional file extension filter (e.g. 'py', 'js').	text	No	(no default)

Output Concepts

Concept	Description	Type
code	A list of code search results with file name, path, SHA, URL, repository, and score.	github code search result

Examples

Search for code in a repository

search code in "kognitos/bdk-api" with
    the query is "def connect"

Search for Python files containing a specific term

search code in "kognitos/bdk-api" with
    the query is "FilterExpression"
    the extension is "py"

to update a (pull request) in a repository source

Update a pull request for a specified GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
pull request	The details required to update a pull request. It includes the pull request number and can contain title, body, and state.	github pull request	Yes	(no default)

Output Concepts

Concept	Description	Type
pull request	The pull request just updated.	github pull request

Examples

Update a pull request from a repository

the pull request is '{"number": "1", "title": "This is the edited title", "body": "This is the edited body", "state": "open"}'
update the pull request in "kognitos/bdk-api"

to update an (issue) in a repository source

Update an issue for a specified GitHub repository.

Input Concepts

Concept	Description	Type	Required	Default Value
repository source	The source of the repository. It is a combination of the owner and the repository name, separated by a forward slash. For example, 'torvalds/linux'.	conceptual or text	Yes	(no default)
issue	The details required to update an issue. It includes the issue number and can contain title, body, and state.	github issue	Yes	(no default)

Output Concepts

Concept	Description	Type
issue	The issue just updated.	github issue

Examples

Update an issue from a repository

the issue is '{"number": "1", "title": "This is the edited title", "body": "This is the edited body", "state" : "open"}'
update the issue in "kognitos/bdk-api"

Concepts

Github comparison

GitHub Comparison Wrapper class.

Field Name	Description	Type
status	The comparison status (ahead, behind, diverged, identical).	text
ahead_by	The number of commits ahead.	number
behind_by	The number of commits behind.	number
total_commits	The total number of commits.	number
html_url	The HTML URL of the comparison.	optional[text]
files	The list of file diffs in the comparison. Empty when the refs are identical.	optional[list of github file diff]

Github file diff

GitHub File Diff Wrapper class.

Field Name	Description	Type
filename	The name of the changed file.	text
status	The status of the change (added, removed, modified, renamed, copied, changed, unchanged).	text
additions	The number of lines added.	number
deletions	The number of lines deleted.	number
changes	The total number of lines changed.	number
patch	The unified diff patch (None for binary files).	optional[text]
previous_filename	The previous filename (only for renames).	optional[text]
sha	The SHA of the file.	optional[text]

Github issue

GitHub Issue Wrapper class.

Field Name	Description	Type
number	The number of the issue. Optional since is None in case of creating an issue.	optional[number]
title	The title of the issue. Optional since can be None in case of editing an issue.	optional[text]
body	The body of the issue. Optional since can be None in case of editing an issue.	optional[text]
state	The state of the issue. Optional since is None in case of creating an issue.	optional[text]
labels	The labels of the issue. Optional since can be None in case of editing an issue.	optional[list of github label]
user	The user of the issue. Optional since is None in case of creating an issue.	optional[github user]

Github label

GitHub Label Wrapper class.

Field Name	Description	Type
color	The color of the label.	text
description	The description of the label.	optional[text]
name	The name of the label.	text
url	The URL of the label.	text

Github user

GitHub User Wrapper class.

Field Name	Description	Type
login	The login of the user.	optional[text]
id	The ID of the user.	optional[number]
type	The type of the user.	optional[text]

Github pull request

GitHub Pull Request Wrapper class.

Field Name	Description	Type
number	The number of the pull request. Optional since is None in case of creating a pull request.	optional[number]
head	The head of the pull request. Optional since can be None in case of editing a pull request.	optional[github pull request part? or text]
title	The title of the pull request. Optional since can be None in case of editing a pull request.	optional[text]
base	The base of the pull request. Optional since can be None in case of editing a pull request.	optional[github pull request part? or text]
body	The body of the pull request. Optional since can be None in case of editing a pull request.	optional[text]
state	The state of the pull request. Optional since is None in case of creating a pull request.	optional[text]
author	The login username of the pull request author.	optional[text]
updated_at	The timestamp when the pull request was last updated.	optional[text]
merged_at	The timestamp when the pull request was merged, if applicable.	optional[text]
merged	Whether the pull request has been merged.	optional[boolean]
url	The API URL of the pull request.	optional[text]
html_url	The HTML URL of the pull request.	optional[text]
labels	The list of label names on the pull request.	optional[list of text]

Github commit

GitHub Commit Wrapper class.

Field Name	Description	Type
commit	The commit.	optional[github git commit]
sha	The SHA of the commit.	optional[text]
stats	The commit stats.	optional[github commit stats]
url	The URL of the commit.	optional[text]

Github git commit

GitHub Git Commit Wrapper class.

Field Name	Description	Type
author	The author of the commit.	optional[github git author]
committer	The committer of the commit.	optional[github git author]
message	The message of the commit.	optional[text]
sha	The SHA of the commit.	optional[text]

Github commit stats

GitHub Commit Stats Wrapper class.

Field Name	Description	Type
total	The total number of commits.	number
deletions	The number of deletions.	number
additions	The number of additions.	number

Github file content

GitHub File Content Wrapper class.

Field Name	Description	Type
name	The name of the file or directory.	text
path	The path of the file or directory.	text
sha	The SHA of the content.	text
size	The size of the content in bytes.	number
type	The type of the content (file, dir, symlink, submodule).	text
content	The decoded text content (files only).	optional[text]
encoding	The encoding of the content.	optional[text]
html_url	The HTML URL of the content.	optional[text]
download_url	The download URL of the content.	optional[text]

Github repository

GitHub Repository Wrapper class.

Field Name	Description	Type
branches_url	The branches URL.	text
commits_url	The commits URL.	text
description	The description of the repository.	text
git_commits_url	The git commits URL.	text
git_tags_url	The git tags URL.	text
git_url	The git URL.	text
name	The name of the repository.	text

Github team

GitHub Team Wrapper class.

Field Name	Description	Type
id	The ID of the team.	number
url	The URL of the team.	text
name	The name of the team.	text
slug	The slug of the team.	text
description	The description of the team.	text
privacy	The privacy of the team.	text
permission	The permission of the team.	text
members	The members of the team.	optional[list of github user]
members_url	The members URL of the team.	optional[text]
repositories_url	The repositories URL of the team.	text

Github code search result

GitHub Code Search Result Wrapper class.

Field Name	Description	Type
name	The name of the file.	text
path	The path of the file.	text
sha	The SHA of the file.	text
html_url	The HTML URL of the file.	optional[text]
repository	The full name of the repository (e.g. owner/repo).	optional[text]
score	The relevance score of the search result.	optional[number]