References are a powerful feature that allows links to be created between Tuleap objects. Based on a text pattern, Tuleap automatically generates hyperlinks to the target object.
What is a reference in Tuleap?
In Tuleap, a reference is a way to automatically create links between different objects (artifacts, documents, commits, wiki pages, etc.) directly from text. This makes traceability and navigation between related elements much easier.
When entering a follow-up comment or a commit message, any text containing the pattern XXX #NNN is interpreted as a reference to an object of type XXX with the identifier NNN.
For example, artifact #123 is recognized as a reference to artifact number 123, so Tuleap automatically creates a hyperlink pointing directly to the details of artifact 123.
It is also possible to reference an object belonging to another project. In that case, you must use XXX#project_id:NNN or XXX #project_name:NNN to reference object XXX number NNN belonging to the project whose ID is project_id or whose short name project_name
For example, doc #myproj:567 is a reference to document 567 in the myproj project.
Some reference patterns may require multiple parameters. In that case, use / as a separator between parameters. For example, git #a_repo/6eef1d01 creates a reference to the Git commit 6eef1d01 in the a_repo repository.
Platforms and projects can define their own custom references (configured by project administrators).
What is a documentation reference?
A documentation reference corresponds to:
A link to a document stored in Tuleap.
An explicit mention of a document in an artifact or description.
A logical association between a document and a project element.
References make it possible to:
Avoid file duplication.
Guarantee a single source of truth.
Facilitate access to information.
Where to find references in Tuleap?
In the project MediaWiki
The wiki is the main area for:
Writing documentation.
Structuring thematic content.
Linking pages together.
Each page can include internal or external references.
In documents
The documents area allows you to:
Store PDF, Word, Excel files, images, etc.
Maintain a structured document hierarchy.
References can be:
Inserted directly into files.
Added via comments or metadata.
In tasks, stories, and artifacts
In tickets or artifacts, cross-references (links to wiki pages or other Tuleap elements) are used to explain, document, or clarify a requirement.
Types of references
Type | Usage | Example |
|---|---|---|
Internal reference | Link to a wiki page or an artifact | [[Guide%20d’utilisation]] |
External reference | Link to an external resource | [Official Git documentation](https://git-scm.com/doc) |
Attached document reference | Link to a file in “Documents” | Documents/Specs/Architecture.pdf |
How to add a reference
In the project MediaWiki
Open the wiki page to edit.
Add a reference and save.
[[PageName]]or
[Link text](URL)In a ticket / artifact
In the description or comment field, insert the link and save.
Example:
See the documentation: [[WikiPage]]Best practices
Use clear and consistent names: Tuleap_User_Guide, Dev_Process.
Regularly check that links are not broken.
Update outdated content after team meetings.