Using GitLab Macros
Using the GitLab Macro
The GitLab macro allows you to display GitLab content directly within Confluence pages using standard GitLab URLs.
The macro automatically detects the link type and renders a rich preview for supported GitLab content.
Supported Content Types
The GitLab macro currently supports:
Projects
Merge requests
Issues/work items
Pipelines
Source Code
Simply paste a supported GitLab URL into the macro to display the corresponding content.
Adding the GitLab Macro
To insert GitLab content into a Confluence page:
Edit a Confluence page
Paste a supported GitLab URL
Publish or update the page
The macro will automatically retrieve and display GitLab metadata.
Supported GitLab Links
Merge Requests
You can display GitLab merge requests directly within Confluence.
Example:
https://gitlab.com/group/project/-/merge_requests/1
The macro may display information such as:
Merge request title
Status
Author (avatar)
Labels
Issues
You can display individual GitLab issues using a direct issue link.
Example:
https://gitlab.com/group/project/-/issues/2
The macro may display:
Issue title
Status
Labels
Assignee (avatar)
Repositories (Projects)
Repository links display project-level information.
Example:
https://gitlab.com/group/project
The macro may display:
Project name
Branch count
Stars
Forks
Pipelines
Repository links display project-level information.
Example:
https://gitlab.com/group/project/-/pipelines/123456789
The macro may display:
Pipeline number
Status
Branch
Source File
Repository links display project-level information.
Example:
https://gitlab.com/group/project/-/blob/master/README.md
The macro may display:
File Name
Branch
Code
Supported GitLab Deployments
The macro supports:
GitLab SaaS
GitLab On-Premises
For On-Premises deployments, the GitLab instance must be publicly accessible and properly configured by a Confluence administrator.
Best Practices
We recommend:
Using direct links to specific resources
Verifying repository permissions before sharing pages
Keeping repository URLs consistent across documentation
Using merge request previews in release notes and technical documentation
Common Use Cases
Teams commonly use the GitLab macro for:
Engineering Documentation
Link implementation details directly to merge requests and issues.
Release Notes
Embed completed merge requests and resolved issues.
Incident Reviews
Reference fixes, discussions, and deployment changes.
Product Planning
Connect roadmap items to GitLab issues and development work.
Troubleshooting
If the macro does not render correctly:
Verify the GitLab URL is valid
Confirm the repository is accessible
Check that the GitLab integration has been configured
Ensure the Personal Access Token is still valid
If issues persist, contact your Confluence administrator.
Related Guides
Installation & Configuration
Troubleshooting
FAQ & Support
Updated: