GitLab platform#

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

Our GitLab Platform uses the gidgetlab library, which is an asynchronous GitLab API wrapper for Python.

Note

There are some properties the agent needs in order to properly set GitLab 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')
...
gitlab_platform = agent.use_gitlab_platform()

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

# Importing the events
from besser.agent.platforms.gitlab.gitlab_webhooks_events import MergeRequestOpened, IssuesOpened, WikiPageCreated, Push

# Merge Request
idle.when_event(MergeRequestOpened()).go_to(merge_state)
# Issues
idle.when_event(IssuesOpened()).go_to(issue_state)
# Wiki Pages
idle.when_event(WikiPageCreated()).go_to(wiki_state)
# Push
idle.when_event(Push()).go_to(push_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 gitlab 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 opening events to add a thanking message as comment:

# How to import the Issue class
from besser.agent.platforms.gitlab.gitlab_objects import Issue

def issue_body(session: Session):
    # Access through the Session to the IssuesOpened GitLabEvent that triggered the transition
    event: GitLabEvent = session.event
    # Extract useful information
    user_repo = event.payload['project']['path_with_namespace'].split('/')
    issue_iid = event.payload['object_attributes']['iid']
    # Get the issue as object
    issue: Issue = gitlab_platform.get_issue(
        user=user_repo[0],
        repository=user_repo[1],
        issue_number=issue_iid)
    # Add a thanking message to the opened issue
    gitlab_platform.comment_issue(issue,
        'Hey,\n\nThanks for opening an issue!<br>We will look at that as soon as possible.')

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

Gitgetlab Wrapper#

The BAF GitLab Platform wraps some functionalities of the gidgetlab 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 GitLabPlatform class. It forwards the method calls not implemented in GitLabPlatform to the underlying GitLabAPI (gidgetlab.aiohttp.GitLabAPI class, which is an extension of the abstract gidgetlab.abc.GitLabAPI class).

That means you can call any function from the GitLabPlatform as you would do in the GitLabAPI!

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 GitLabPlatform, you can simply call it and it will be forwarded:

def example_body(session: Session):
    payload = gitlab_platform.getitem(f'/projects/NAMESPACE%2FPROJECT_PATH/repository/contributors')

Note

Here we use the Namespaced path notation (i.e. “NAMESPACE%2FPROJECT_PATH”) for the project, but using project id works too.

API References#