# GitHub
{% hint style="info" %}
The following documentation is for **GitHub v2.0.1** *(BDK)*.
{% endhint %}
## 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**](#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 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`](#github-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`](#github-pull-request) | The pull request just created. | `github pull request` |
**Examples**
Create a pull request from a repository
```generic
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`](#github-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`](#github-issue) | The issue just created. | `github issue` |
**Examples**
Create an issue from a repository
```generic
the issue is '{"title": "This is the title", "body": "This is the body"}'
create an issue in "kognitos/bdk-api"
```
### to get the (commits) from a repository source
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`](#github-commit) | 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
```generic
get some commits from "kognitos/bdk-api"
```
Retrieve the list of commits from a specific branch of a repository
```generic
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
```generic
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 (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`](#github-issue) | A list of issues with details such as title, description, and URL. | `github issue` |
**Examples**
Retrieve the list of issues from a repository
```generic
get some issues from "kognitos/bdk-api"
```
Retrieve the list of closed issues from a repository
```generic
get some issues from "kognitos/bdk-api" with
the state is closed
```
### 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`](#github-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
```generic
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 |
**Output Concepts**
| Concept | Description | Type |
| --------------------------------------- | ------------------------------------------------------------------------- | --------------------- |
| [`pull requests`](#github-pull-request) | 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
```generic
get some pull requests in "kognitos/bdk-api"
```
Retrieve the list of open pull requests from a repository
```generic
get some pull requests in "kognitos/bdk-api" with
the state is open
```
### 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`](#github-repository) | A list of repositories with details such as repository name, description, and URL. | `github repository` |
**Examples**
Retrieve the list of repositories from an organization
```generic
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`](#github-team) | A team with details such as team name. | `github team` |
**Examples**
Retrieve the team from an organization
```generic
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`](#github-team) | A list of teams with details such as team name. | `github team` |
**Examples**
Retrieve the list of teams from an organization
```generic
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`](#github-user) | The user details such as name, login, and email. | `github user` |
**Examples**
Retrieve the details of a user
```generic
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`](#github-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`](#github-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"
```generic
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 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`](#github-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`](#github-pull-request) | The pull request just updated. | `github pull request` |
**Examples**
Update a pull request from a repository
```generic
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`](#github-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`](#github-issue) | The issue just updated. | `github issue` |
**Examples**
Update an issue from a repository
```generic
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 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`](#github-label) | The labels of the issue. Optional since can be None in case of editing an issue. | `optional[list of github label]` |
| [`user`](#github-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]` |
### Github commit
GitHub Commit Wrapper class.
| Field Name | Description | Type |
| ------------------------------- | ---------------------- | ------------------------------- |
| [`commit`](#github-git-commit) | The commit. | `optional[github git commit]` |
| `sha` | The SHA of the commit. | `optional[text]` |
| [`stats`](#github-commit-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`](#github-git-author) | The author of the commit. | `optional[github git author]` |
| [`committer`](#github-git-author) | 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 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`](#github-user) | 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` |