Here’s a comprehensive GitLab reference guide on how to link, reference, and organize various entities (like issues, jobs, users, environments, etc.) across GitLab descriptions, wikis, commit messages, MRs, and more.

---

📘 GitLab Reference & Linking Guide (v18.x compatible)

GitLab provides Markdown and keyword-based shortcuts to cross-reference nearly every object in the system for traceability, collaboration, and automation.

---

✅ 1. Issues

🔹 Where to Reference

• Commit messages: Fixes #123
• Merge Request description: Closes #123
• Comments, Wiki, Readme: #123

🔹 Format

#123              // Just refers to issue
Fixes #123        // Closes on merge
See issue #123    // Mentions without closing
Code language: PHP (php)

---

✅ 2. Merge Requests (MRs)

🔹 Where to Reference

• Wiki: !45
• Issues, Comments: See !45
• Commit Messages (rare)

🔹 Format

!45
See merge request !45

---

✅ 3. Commits

🔹 Where to Reference

• Issues, MRs: abcd1234 or project@abcd1234

🔹 Format

abcd1234              // Short SHA
project@abcd1234      // Cross-project
Code language: JavaScript (javascript)

---

✅ 4. Jobs (CI/CD)

🔹 Where to Reference

• Pipeline tab or job logs in UI (not Markdown-accessible)
• Use direct links or job artifacts in comments or wiki

🔹 Format (Manual linking)

[View Job Log](https://gitlab.com/namespace/project/-/jobs/123456789)
Code language: JavaScript (javascript)

---

✅ 5. Milestones

🔹 Where to Reference

• Issues, MRs, Wiki: %milestone_name

🔹 Format

%v1.0
Targeted for %Q2-Release
Code language: CSS (css)

---

✅ 6. Requirements (GitLab Ultimate)

🔹 Where to Reference

• Issues, MRs, Descriptions, Wiki: REQ-1, requirements#123

🔹 Format

Relates to requirements#12
Code language: CSS (css)

Enabled under Requirements Management in project settings.

---

✅ 7. Users

🔹 Where to Mention

• Any Markdown-supported field: descriptions, comments, commit messages

🔹 Format

@username
Assigned to @john_doe
Code language: CSS (css)

---

✅ 8. Labels

🔹 Where to Use

• Issue or MR references: ~"bug" or ~bug

🔹 Format

~"feature"
~backend
Code language: JavaScript (javascript)

---

✅ 9. Environments (CI/CD)

🔹 Where to Reference

• Pipeline views, API, job logs

🔹 Format

[View Staging](https://gitlab.com/namespace/project/-/environments/123)
Code language: JavaScript (javascript)

---

✅ 10. Epics (GitLab Premium+)

🔹 Where to Reference

• Issues, MRs, descriptions, comments: &123

🔹 Format

Part of epic &45

---

✅ 11. Snippets

🔹 Where to Reference

• Wiki, comments: $snippet_id

🔹 Format

$42

---

✅ 12. Wiki Pages

🔹 Where to Reference

• Markdown everywhere

🔹 Format

[Deployment Guide](../wikis/deployment)

---

✅ 13. Projects

🔹 Cross-project linking:

group/project#123         // Issue
group/project!456         // MR
group/project@SHA         // Commit
Code language: PHP (php)

---

✅ 14. Pipeline Status Badges

[![pipeline status](https://gitlab.com/group/project/badges/main/pipeline.svg)](https://gitlab.com/group/project/pipelines)
Code language: JSON / JSON with Comments (json)

---

📌 Markdown Reference Shortcuts Summary

Reference Type	Syntax Example	Description
Issue	#123	Links to issue
Merge Request	!45	Links to MR
Commit	abcd1234	Links to commit
Milestone	%v1.0	Links to milestone
Label	~bug	Links to label
User	@username	Mentions user
Epic	&12	Links to epic (Premium+)
Requirement	requirements#123	Links to requirement (Ultimate)
Snippet	$42	Links to code snippet
Environment Link	Direct URL	Link to job/env logs
Cross-project	group/project#123	Ref to other repo issue/MR

---

🧠 Tips

• GitLab autolinks most entities with typeahead autocomplete when typing @, #, !, etc.
• Use templates (issue/MR/wikis) to enforce referencing conventions.
• Use custom sections in MRs like: ### Linked Issues Fixes #123 ### Related MRs See !45

---