How to create a bot for code reporting activities

In this article we present how to create weekly reports describing status and contributions of code repositories on GitHub. Reports are published on a Slack Workspace, allowing tech and non-tech people to access updates on repository status.

Requirements:

• Slack Workspace for company communications.
• Code repositories hosted on GitHub.

Let’s keep people informed

The number and variety of projects involving a tech team can make it increasingly difficult to keep track of progress on code repositories. To solve this issue, we created an automatic weekly report describing the status of code repositories and individual project contributions.

By using our free and open source code, an automatic weekly report will be shared with your company through Slack:

An example of a weekly report generated by our bot on Slack

Why Slack?

Developers can get all information about development progresses directly from the organization’s repositories. However, people with little tech-background can find it difficult to browse on a Github repository, simply because they are not allowed to access certain repositories, or they don’t know what merge, fix or branch mean!

Slack is the preferred communication channel of many tech-oriented companies, and is the place where both tech and non-tech people meet to share messages, information, and ideas.

By automatically sharing a weekly report on Slack, we are giving the full team access to information that was otherwise previously consumed only by Github users, making the tracking process easier and more transparent.

Benefits

We believe in making information easily accessible and consumable. We believe that a well-informed person has a stronger context to make better decisions and initiatives (context over control).

Starting from this assumption, we identified some of the benefits arising from the implementation of an automatic weekly report on code repositories:

• Knowledge flow: teams working on different projects have a broader view on what is happening across the teams and they can check if there is something interesting/useful for their own activities.
• Performance tracking: by looking at which task will be included in the next release, Project Manager and Product Owner can quickly assess whether the performance of the team is in line with what is expected (this is particularly effective when team adopts the conventional commit format, which is very comprehensible and explicit).

Development Health Status Checks:

Among the benefits of automatic weekly reports in performance tracking, a special mention goes to the evaluation of the development process through indicators such as:

• too few contributions: it could indicate that the team is tired or unmotivated.
• number of proposed contributions largely exceeds accepted ones: it could indicate that developers spend the majority of their time working on dedicated tasks, and have little time for reviewing/helping their peers (high-level of parallelism).
• number of proposed contributions largely exceeds reviewed ones: it could indicate that your code is being shipped with an excessively high level of confidence, and that’s not what you really want.
• some developers have a low rate of code review: it could indicate that certain developers over-invest their time on coding and spend too little time on reviewing, eventually slowing down the pace of the project. In addition, those developers could remain isolated in their projects and cut out on updates about projects’ progression.
• too many closed PR: it could indicate that the team is producing a lot of attempts which are then discarded. This could reflect a weak knowledge/task scope around the project.

The code

The source code is open and free to use. If your repositories are hosted on GitHub and your company uses Slack, this tool is almost ready to go.

You can find the repository here: https://github.com/heritageholdings/github-report

For further details and setup instructions not provided in this article, you can see the README.

The whole project is written in Python, and the code is pretty basic and simple. The external libraries used for this project are:

• PyGithub: to interact with GitHub APIs.
• slack: to send messages to Slack channel.
• slackclient: required by slack.
• certifi: required by slackclient to suppress some warnings.

The code will scan for data and generate reports for all the repositories set in the env variable (GH_COMPANY_REPOSITORIES).

How it works

In order to scan each repository and generate the report, the code follows these steps:

1.It retrieves PRs which have been updated in the last X days (configurable in DAYS_SPAN).

2.It groups the PR by state:

merged (it could also be included in reviewed)

open

closed

reviewed (it could also be included in merged)

draft

3.It retrieves PRs which are currently in the Pull requests section (open + draft).

4.For PRs which have already been merged, it extracts each developer’s contribution.

A contribution is defined as the sum of lines changed in the code (additions + deletion). It’s a basic KPI to represent the impact of a single developer’s contribution

5.It builds the Slack messages reporting the repository stats overview.

6.It sends messages inside the report thread to detail the list of the merged PRs and the developer stats.

Future improvements and extensions

• Historical analytics: If your organization doesn’t already leverage tickets/tasks tracking tools such as Pivotal, JIRA, Asana etc, you can store report data in order to perform historical analytics and to assess trends, performance, bugs spawning over features/releases, etc.
• Forward messages to multiple destinations, such as Slack, Notion update, email, etc.
• Build the report as PDF, which can be emailed to the whole company as an update newsletter.

Written by Matteo Boschi and HTECH Team