Getting started with GitProject Health

This page presents the starting point if you want to have high-level information about your repositories’ health.

What is GitProject Health

GitProject health is a suit of importers, models, and visualizations, that enable the analysis of your repositories. For instance, you will be able to see the repositories with failing pipelines, the numbers of commits by projects, the authors of commits, etc. It is also possible to link the repository commits with a Famix model to have even more information.

Installation GitProjectHealth

To install GitProjectHealth, you’ll need a Moose11+ image (see the install Moose page).

In the Moose image, in a playground (Ctrl+O, Ctrl+W), perform:

Metacello new
  repository: 'github://moosetechnology/GitProjectHealth:main/src';
  baseline: 'GitLabHealth';
  onConflict: [ :ex | ex useIncoming ];
  onUpgrade: [ :ex | ex useIncoming ];
  onDowngrade: [ :ex | ex useLoaded ];
  load

This command will load the GitProjectHealth project as well as all its Pharo dependencies.

The project was originally made for GitLab repositories analysis, so some feature might be available only for GitLab. We try to update this documentation with all information as much as we can, do not hesitate to do a pull request if some feature are missing

Import a model

Once the GitProjectHealth project has been loaded, one has to import the project from the Git server to the Moose image. As of today, we import a group of repositories.

Import a group from GitLab

In a playground (Ctrl+O, Ctrl+W).

glhModel := GLHModel new.

glhApi := GLHApi new
    privateToken: '<Your private token>';
    baseAPIUrl:'https://gitlab.myPrivateHost.com/api/v4';
    yourself.

glhImporter := GLHModelImporter new
    glhApi: glhApi;
    glhModel: glhModel.


"137 is the ID of the a Group, you can find the number in the webpage of every project and group"
glhImporter importGroup: 137.

You can also import all available top-level groups and then iterate:

groups := glhImporter importAllGroups.
groups do: [:group | 
  glhImporter importGroup: group id.
]

Import a group from GitHub

In a playground (Ctrl+O, Ctrl+W).

glhModel := GLHModel new.

githubImporter := GHModelImporter new glhModel: glhModel; privateToken: '<my private token>'; yourself.

githubImporter importGroup: 'moosetechnology'.

More commits extracted

You might want to gather more commits for a specific repository. To do so in GitLab, we added the following API

myProject := ((glhModel allWithType: GLHProject) select: [ :project | project name = '<my projectName>' ]) anyOne.

glhImporter importCommitsOf: myProject withStats: true until: '2023-01-01' asDate.

Import Merge Requests information

It is possible to extract MergeRequests of a project. To avoid too many REST API requests, you should do it in multiple steps.

First, import basic information.

(glhModel allWithType: GLHProject) do: [:project | 
  glhImporter importMergeRequests: project
]

This will only import the first 20 merge requests for each project. However, one can also use the method importMergeRequests:since:until: to import all merge request since a specific date

Then, you can import more data for each MergeRequest

(glphModel allWithType: GLPHEMergeRequest) do: [ :mr |
  "Extract information about Merge Request approvals and review"
  glhImporter importMergeResquestApprovals: mr.
  "Extract information about Author, Mergers, etc."
  glhImporter importMergeResquestAuthor: mr.
].

Visualize

To visualize the group’s “health”

dritGroup := (glhModel allWithType: GLHGroup) detect: [ :group | group id = 137 ].
canvas := (GLHGroupVisualization new forGroup: { dritGroup } ).
canvas open.

Export

To export the visualization as an svg image

dritGroup := (glhModel allWithType: GLHGroup) detect: [ :group | group id = 137 ].
canvas := (GLHGroupVisualization new forGroup: {dritGroup}).
canvas open.

canvas svgExporter
  withoutFixedShapes;
  fileName: 'drit-group-health';
  export.