Create Github plugin

[jmcook1186]

sub of #898

what

A plugin that requests data about Github repositories using the Github API using personal authorization tokens stored in environment variables.

context

Code storage and distribution is an important component of quantifying the environmental impacts of software projects. Github is the industry standard platform for hosting code. They expose an API that serves repository metrics incuding repo size and frequency of clones etc that can be used to assess the environmental impacts of the project storage and distribution.

Specifically, the plugin should return the following:

value	API endpoint	Docs link
number of time the repo was clones	curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/repos/OWNER/REPO/traffic/clones	https://docs.github.com/en/rest/metrics/traffic?apiVersion=2022-11-28
repo size in kb	curl -L \ -H "Accept: application/vnd.github+json" \ -H "Authorization: Bearer <YOUR-TOKEN>" \ -H "X-GitHub-Api-Version: 2022-11-28" \ https://api.github.com/orgs/ORG/repos	https://docs.github.com/en/rest/repos/repos?apiVersion=2022-11-28

SoW

• create plugin that returns the requested data from theGithub API
• create in dedicated IF repository (not a builtin)
• add plugin to Explorer

Acceptance criteria

• The plugin retrieves size and clones data from the Github API. size should be converted from kb to GB for consistency with other IF plugins.

Note that the traffic metrics only extend back as far as the most recent four weeks. You can request the total for any of those weeks or the whole preceding month. I think the right way to handle this in IF is to offer two options: last week or last month.

GIVEN the plugin works as expected and I have a valid auth token in .env
WHEN I run the following manifest:

name: github demo
description:
tags:
initialize:
  plugins:
    github-plugin:
      method: GithubAPI
      path: github-api
      config:
        repo-name: Green-Software-Foundation/if
        time: 'week' # can be week or month
tree:
  children:
    github:
      pipeline:
        observe:
         - github-plugin
      config:
      defaults:
      inputs:
        - timestamp: 2023-08-06T00:00
          duration: 2419200

Then I get the following output (the last week's clones and the current repo size converted from kb to GB:

name: github demo
description:
tags:
initialize:
  plugins:
    github-plugin:
      method: GithubAPI
      path: github-api
      config:
        repo-name: Green-Software-Foundation/if
        time: 'week' # can be week or month
tree:
  children:
    github:
      pipeline:
        observe:
         - github-plugin
      config:
      defaults:
      inputs:
        - timestamp: 2023-08-06T00:00
          duration: 2419200
      outputs:
        - timestamp: 2023-08-06T00:00
          duration: 2419200
          size: 0.0017
          clones: 34
      

• The plugin is available on https://explorer.if.greensoftware.foundation

Note to be listed it has to meet some basic standards for documentation and repository structure.

[zanete]

@manushak please take a look through the AC to confirm you're happy with it

[manushak]

yeah, it seems clear

[manushak]

@jmcook1186 can you provide me the dedicated repo for this plugin (in SoW create in dedicated IF repository (not a builtin)) ?

[manushak]

@jmcook1186 we can't get repo clones for a month; the maximum range is 14 days. According to the GitHub API:
Get the total number of clones and breakdown per day or week for the last 14 days. Timestamps are aligned to UTC midnight of the beginning of the day or week. Week begins on Monday.

We can skip the time property because we have duration and timestamp, unless these properties are not used. If the range exceeds 14 days, we can show data for 14 days and display a warning.

What do you think?

[jmcook1186]

Hi @manushak

ok interesting - could we do 2 week max, but infer an actual time range from the timesteps and duration?

Making you a repo now.

[manushak]

thanks @jmcook1186 for the repo
yeah, the logic that I've created is working like you mentioned.

[zanete]

Minor update required to update the IF core version if there are no new comments

[zanete]

Manifest examples need to be updated after phased execution release