What differs between the forges

edhil does the same on GitLab and on Forgejo: the same commands, the same checks, the same labels, the same epics and work items, and the same messages, which say which forge they come from. The configuration has one section for the forge, and nothing else in the way of working depends on which one it is. This page lists the few places where the forges are not the same, so that you know what to expect.

An epic is linked to its work items, and a project to its epics, so that edhil work-items can show the tree and edhil import can add to an epic.

  • On GitLab the links are related-issue links. They have no direction: an epic and a work item are related to each other, and edhil tells what each one is by its labels (Epics, Work Items, Projects).
  • On Forgejo the links are issue dependencies, and they have a direction: an epic depends on each of its work items, and a project depends on each of its epics. Every issue of a link must be in the configured repository; a dependency on an issue of another repository is ignored.

A link that was made by hand has to follow the same rule on Forgejo: to link a work item to an epic, add the work item as a dependency of the epic, and not the other way round.

Dependencies must be enabled on Forgejo

Forgejo has issue dependencies as a setting of each repository. When they are disabled, edhil cannot read or make the links, and the command stops with a message that names the repository:

Issue dependencies are disabled in 'myowner/myrepo' on Forgejo: enable them in the settings of the repository

Enable them in the settings of the repository and run the command again. GitLab has no such setting.

Closing an epic or a project on Forgejo

edhil does not close issues; you close them when you are satisfied. On Forgejo the direction of the links has a consequence for the order: the server refuses to close an issue while an issue that it depends on is open. So close the work items first, then the epic, and the project after its last epic. GitLab accepts any order.

Labels

edhil creates the labels that an import needs (Epics, Work Items, and the label of the project) and shows them before the question. A label that exists is used as it is and is never changed.

  • On GitLab the labels are the labels of the project.
  • On Forgejo a label can be a label of the repository or, when the repository belongs to an organization, a label of the organization. Both are read, and a label that exists in either is used. A label that is missing is created in the repository. Creating a label of the organization is not something edhil does; that needs the scope write:organization and is done by hand.

Addresses

The links that edhil import prints are built from the url of the section and the project or repository:

https://gitlab.com/mygroup/myproject/-/issues/14
https://forgejo.example.com/myowner/myrepo/issues/14

The token

On GitLab the token is a personal access token with the api scope. On Forgejo it is an access token for the issues of the repository; see the token for the scopes that were used when edhil was checked against a Forgejo server, and Checking edhil against a Forgejo server for how to check it again.

What is the same

  • The issue numbers that you give to edhil implement and edhil import --epic are the numbers of the issues in the project or the repository.
  • edhil work-items reads the open issues 50 at a time and stops with an error when there are more than 20000, on both.
  • A read that fails with a network error, a server error or too many requests is tried again, as many times as read_retries says. A request that creates or changes something is never repeated.
  • An import that fails halfway lists what it created, and can be finished by hand or with import --epic.
  • The epic document format, the verification steps and the journal do not depend on the forge.