GitHub platform#

The GitHub Platform allows an agent to receive events from GitHub’s webhooks and perform actions on repositories through the GitHub API.

Our GitHub Platform uses the gidgethub library, which is an asynchronous GitHub API wrapper for Python.

Note

There are some properties the agent needs in order to properly set GitHub and webhook connections. More details in the configuration properties documentation.

How to use it#

After you instantiate your agent, simply call the following function:

agent = Agent('example_agent')
...
github_platform = agent.use_github_platform()

After that, you can use the different events sent by GitHub to trigger transitions in your agent.

# Pull Request
idle.when_event(PullRequestOpened()).go_to(pull_state)
# Issues
idle.when_event(IssuesOpened()).go_to(issue_state)
# Labels
idle.when_event(LabelCreated()).go_to(label_state)
# Stars
idle.when_event(StarCreated()).go_to(star_state)

Note

The agent needs to provide a public URL to receive the webhooks. For local testing you can use ngrok

In addition to webhooks events, the github platform offers:

  • Access to the payload of the received event

  • Wrapper classes on top of the issues and users payload

  • Methods to open, get, comment, label and assign a user to an issue

These abstractions allows to receive webhooks events and perform agent actions on the repository as a reaction. The following example wait for issues to open to add a thanking message as comment:

# How to import the Issue class
from besser.agent.platforms.github.github_objects import Issue

def issue_body(session: Session):
    # Access through the Session to the IssuesOpened GitHubEvent that triggered the transition
    event: GitHubEvent = session.event
    # Wrap the issue object of the payload in our abstraction
    issue = Issue(event.payload['issue'])
    # Add a thanking message to the opened issue
    github_platform.comment_issue(issue
        f'Hey,\n\nThanks for opening an issue {issue.creator.login}!<br>We will look at that as soon as possible.')

⏳ We are working on providing abstractions for more concepts than issues, so stay tuned!

Gidgethub Wrapper#

The BAF GitHub Platform wraps some functionalities of the gidgethub library (such as handling webhooks or act on issues), but not all of them.

In order to use other features not included in BAF yet, we included a __getattr__ function in the GitHubPlatform class. It forwards the method calls not implemented in GitHubPlatform to the underlying GitHubAPI (gidgethub.aiohttp.GitHubAPI class, which is an extension of the abstract gidgethub.abc.GitHubAPI class).

That means you can call any function from the GitHubPlatform as you would do in the GitHubAPI!

Let’s see an example.

You could use getitem to get the list of contributors to a repository. Since this is not integrated in our GitHubPlatform, you can simply call it and it will be forwarded:

def example_body(session: Session):
    payload = github_platform.getitem(f'/repos/OWNER/REPO/contributors')

API References#