Getting started with GitProjectHealth

This page takes you from an empty Moose image to a first answer about your repositories. It takes about ten minutes, plus the import time.

Prerequisites

A Moose image (see Install Moose). This documentation was checked with Moose on Pharo 13.
For platform importers, an access token (see below). The local importer needs no token, only a clone on disk.
All the code below is Pharo code, to run in a Playground (Ctrl+O, Ctrl+W): select it and Do it (Ctrl+D) or Inspect it (Ctrl+I).

First import

Install GitProjectHealth. In a Playground, run:

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

This loads the default group: the meta-model, every importer, the analyses and the visualizations. The Jira and Famix connectors are optional groups.

Get an access token for your platform.
In GitLab, open User settings → Access tokens and create a personal access token with the read_api scope (read_repository is also needed if you import files).
In GitHub, open Settings → Developer settings → Personal access tokens. A token with the repo (or fine-grained Contents, Pull requests, Actions: read) permissions is enough.
In Bitbucket Server / Data Center, create an HTTP access token with read permission on the projects and repositories you want to analyze.
No token is needed. Clone the repository on your disk:
Terminal window
git clone https://github.com/moosetechnology/GitProjectHealth.git
Never commit a script containing your token. Prefer reading it from an environment variable, for instance Smalltalk os environment at: 'GITLAB_TOKEN'.

Import. Create an empty model, configure an importer, and import.

model := GLHModel new name: 'my-gitlab-analysis'.

importer := GitModelImporter
  forGitlabHostOn: 'https://gitlab.com/api/v4' "or your own instance, ending with /api/v4"
  withToken: '<YOUR-GITLAB-TOKEN>'
  andModel: model.

"Import the commits of the last 30 days (default of this constructor: 3 days)"
importer withCommitsSince: 30 days.

"A group is identified by its numeric ID, shown on the group page in GitLab"
group := importer importGroup: 1234.

model := GLHModel new name: 'my-github-analysis'.

importer := GitModelImporter
  forGithubWithToken: '<YOUR-GITHUB-TOKEN>'
  andModel: model.

"Import the commits of the last 30 days (default of this constructor: 3 days)"
importer withCommitsSince: 30 days.

"A GitHub organization is imported as a group, identified by its name"
group := importer importGroup: 'moosetechnology'.

model := GLHModel new name: 'my-bitbucket-analysis'.

importer := GitModelImporter
  forBitbucketHostOn: 'https://bitbucket.mycompany.com'
  withToken: '<YOUR-BITBUCKET-TOKEN>'
  andModel: model.

importer withCommitsSince: 30 days.

"A Bitbucket project is imported as a group, identified by its key"
group := importer importGroup: 'MYPROJECT'.

model := GLHModel new name: 'my-local-analysis'.

"The local importer needs a project and a repository pointing to the clone"
repository := GLHRepository new.
repository
  cacheAt: #localImporterReference
  put: '/path/to/GitProjectHealth' asFileReference.
project := GLHProject new
  name: 'GitProjectHealth';
  repository: repository;
  yourself.
model add: project; add: repository.

importer := GitLocalModelImporter new
  glhModel: model;
  withCommitsSince: 30 days;
  yourself.

"Imports every branch and the commits (with diffs) of the period"
importer importRepository: repository.

Importing a large group through an API can take several minutes.

Explore the model. Inspect it (Ctrl+I on model) and browse the entities by type, or open the inspector on the group (group inspect) to get the Group Quality view.

Ask a first question. For instance, who committed the most during the period?

((model allWithType: GLHCommit)
  collect: [ :commit | commit commitCreator ifNil: [ commit author_name ] ])
  asBag sortedCounts

sortedCounts returns the number of commits per user, highest first.

What’s next?

Understand what was imported: the meta-model.
Import more (merge requests, pipelines, files, diffs): importers and configuration reference.
Copy a ready-made script: recipes.
Compute metrics: metrics and analyses.