A the root of the forge, we find users. Each user has several projects which contains repositories, issues, pull requests, milestones, releases, topics, ci and labels.
Note: a repository is a git repository and a project contains one or several git repositories.
For example:
user/
...
_identifiers.json
20.json
20/project/
_identifiers.json
1.json
1/issue/
_identifiers.json
3.json
3/comment/
_identifiers.json
7.json
7/attachment/
_identifiers.json
20.json
1/pull_request/
_identifiers.json
6.json
1/release/
_identifiers.json
1.json
1/asset/
_identifiers.json
10.json
10/content
1/label/
_identifiers.json
2.json
3.json
1/milestone/
_identifiers.json
8.json
9.json
1/topic/
_identifiers.json
1.json
3.json
1/repository/
_identifiers.json
1.json (name="", vcs="git")
1/ (bare git repository)
2.json (name=".wiki", vcs="git")
2/ (bare git repository)
30.json
...
objects/
...
aa/fb/116a0e7674d9d4f79826690c9ba07b47209d8cbdd6fc17432a8d77c688ce
da/14/64fd7ceaf38ff56043bc1774af4fb5cb83ef5358981d78de0b8be5a6fbcb
At each level of the hierarchy we have a json file (named after the index property: index.json) to describe the resource. There is then a folder named after the index property which contains a representation of all its sub-hierarchy.
At each level, folder names correspond to the json files containing the schema; this schema describes the structure of each json files in this folder. In the example above, user/20/project/1/issue/3.json is describe by the schema issue.json.
Reactions (emojis) are described by the reaction.json file, but it would be space consuming to create a json file for each reaction in a comment. For this reason, reactions are directly included to the json file of the comment. Keeping this in mind, the same decision is applied for review comments or labels.
Object storage
A number of resources include objects that are opaque. For instance an issue comment can contain an attachment with a screenshot to illustrate its content.
The object JSON does not contain the object but the hexadecimal
representation of the SHA-256
of its content. The SHA-256 of the object is a reference relative to
the objects directory with following hierarchy:
a subdirectory named with the characters at position 0 and 1
a subdirectory named with the characters at position 2 and 3
a file named with the characters from 4 to 63
Repository
A repository is, as you might expect, the code but it also comes with a json file that describes each sub folders. In the previous example, we can see that our project has two git repositories, one for the code (user/20/project/1/repository/1.json) and another for the wiki (user/20/project/1/repository/2.json).
Identifiers
Pairs of identities mapping one forge to another. The first element is the id in the remote forge, the second element is the id in the local forge.
The problem it solves is that, for example, the first time you mirror an issue from a remote forge to your local forge, it is created and has an identifier.
A week later, when you refresh the issue on your local forge to get modifications from the remote forge, you need to match the identifier of the issue on your local forge with the identifier of the issue on the remote forge.
CI
The CI associated with a project is usually found within the
repository of a project. For instance .gitlab-ci.yml is interpreted
by a GitLab runner that runs the
software it contains. When importing a such project in a GitLab
instance, the project can also be associated with a runner using the
API.