Ferronier-gitlab

A Ferronier plugin to build a user or group page showcasing its projets, with every single piece of data being fetched using the GitLab API, which means repositories can be simply cloned to create such a showcase. See examples for an user and a group.

Walkthrough

1. Fork an existing repository

  1. Fork one of the example repositories.

    This plugins works the same way on groups and users, so you can fork any repository. Here are a some examples, on several GitLab instances:

    Those repository are given as convenient examples where you can just click on the “fork” button, but you can copy their content to any GitLab instance.

  2. Make sure to choose the right project name.

    For instance, if you want to build this showcase as the main page of the group foobar on https://framagit.org, your project name must be foobar.frama.io (frama.io being the domain name associated with GitLab pages on https://framagit.org).

    See the official documentation for more information.

2. Create a GitLab token, and add it to your pipeline variables

Every single piece of information displayed by this plugin is public, and fetched using the Gitlab API, but this API sometimes requires a token to be used.

  1. Create an access token:

    • For a group [2]:

      1. Go to the profile page of your group.

      2. Select Settings > Access tokens.

      3. Select Add new token.

      4. Choose a Token name and a, optionally, a Token description.

      5. Select an expiration date (as far as possible if you do not want to change it often).

      6. Select Maintainer as role, and check read_api.

      7. Select Create group access token, and copy the resulting token, for the next step.

    • For an user [1]:

      1. Go to your profile page (in the upper-right corner, select your avatar).

      2. Select Edit profile.

      3. Select Access > Personal access tokens.

      4. From the Generate token dropdown list, select Legacy token.

      5. Choose a Token name and a, optionally, a Token description.

      6. Select an expiration date (as far as possible if you do not want to change it often).

      7. Check read_api as the only scope.

      8. Select Create token, and copy the resulting token, for the next step.

  2. Add this token as a variable in your pipelines [3]:

    1. Go to the project you created on the previous step.

    2. Select Settings > CI/CD.

    3. Expand Variables.

    4. Select Add variable and fill as details:

      • Key: GITLAB_API_KEY

      • Value: the token you copied in the previous step.

      • Type: keep the default variable.

      • other values: as you wish.

    5. Submit this form, and go to the next step.

3. Run your first pipeline

To build your website for the first time, you have to run a pipeline.

  1. Go to the repository of your project.

  2. Select (in the left column) Build > Pipelines.

  3. Click on the New pipeline button.

  4. Leave everything as-is, and validate with the New pipeline button (again).

Wait for the pipeline to end, and you can navigate to your website with the Gitlab pages button on your project page. The page might be emptier than you expect. If so, setting project, and group or user metadata, might fix it. It will be discussed in a later section.

4. Configure your pipeline to re-run every week or month

The generated website is static: it shows a snapshot of your projects at the time the pipeline ran, and is not automatically updated. To do so, you can configure your repository to rerun the pipeline every week or month.

  1. Go to the repository of your project.

  2. On the left menu, select Build > Pipeline schedules.

  3. Click on the New schedule button (top right).

  4. Choose a relevant description, your timezone, select an interval pattern (monthly (maybe weekly?) seems right: do you really need a shorter interval?), leave everything else as-is, and submit with the Create pipeline schedule button.

5. (Optional) Read and change some options

The ferronier.toml file at the root of the repository (example) have options that are self described, that you can use to fine-tune the output of the website (for instance, you can change the language (if translations in your language are missing, see below), exclude projects, hide topics…).

6. Set your profile, group and project metadata correctly, so that they appear in your showcase

As said (several times!) earlier, every single piece of data displayed in this showcase it fetched using the GitLab API, from your profile, group or project metadata. Let’s discuss them.

User profile

_images/user.png

  1. User name: Edit profile > Main settings > Full name

  2. Avatar: Edit profile > Public avatar. If not set, the first letter of the user name will be used instead.

  3. About you: Edit profile > Main settings > Pronouns, Pronunciation, Location, etc. If some fields are missing (not rendered in the output page), please submit an issue.

  4. Bio (short description): Edit profile > Main settings > Bio

  5. Links: Edit profile > Main settings > Social accounts (note: some accounts are not displayed because of the GitLab API).

  6. Long description: Content of the README file of a project named after your username (important!) (official documentation ).

Group

_images/group.png

  1. Group name: Settings > General > Group name.

  2. Avatar: Settings > General > Avatar. If not set, the first letter of the group name will be used instead.

  3. Number of projects and subgroups: automatic.

  4. Short description: Settings > General > Description.

  5. Badges: Settings > Badges.

  6. Long description: Content of the README file of a project named gitlab-profile (important!) (official documentation ).

Project

_images/project.png

  1. Avatar: Settings > General > Project avatar. If not set, the first letter of the project name will be used instead.

  2. Project name: Settings > General > Project name.

  3. Path: automatic, cannot be changed.

  4. Description: Settings > General > Project description.

  5. Topics: Settings > General > Project topics.

  6. Badges: Settings > General > Badges.

  7. Public page: The URL of the GitLab page (if created) is used.

  8. Links: automatic.

Note that although the project README does not appear in the page, it is used when using the search bar.

Subgroup

_images/subgroup.png

  1. Avatar: Settings > General > Avatar. If not set, the first letter of the group name will be used instead.

  2. Group name: Settings > General > Group name.

  3. Path: automatic, cannot be changed.

  4. Short description: Settings > General > Description.

  5. Badges: Settings > Badges.

  6. Links: automatic.

Note that although the group README (the README of a project named gitlab-profile (official documentation)) does not appear in the page, it is used when using the search bar.

Other software forges?

I (almost) don’t use other forges. However, if you were to write a similar plugin for Forgejo, Github, or any other software forge, I would be happy to reference your project here.

Translations

The template producing the showcase, as well as this documentation, are translated (in French, at the time I am writing this documentation).

Choosing a different language

Change the locale = "en_US" line in the ferrionier.toml file to select another language.

Add a new translation

Pull requests are welcome to translate ferronier-gitlab or its documentation to a new language! Follow this documentation to do so.

About

Footnotes