Release notes, sprint reviews and runbooks all reference GitLab: which merge requests went out, whether the pipeline is green, what the config file says. In Confluence that usually means screenshots and pasted links that are wrong by next week.
And if you run self-managed GitLab, there's an extra catch: Confluence's built-in Smart Links generally don't show preview cards for self-managed instances, so you don't even get a preview.
The usual workarounds
- Screenshots of pipelines and MR lists. They look nice in the review meeting and are outdated straight after.
- Plain links. They work, but readers have to leave the page, and many stakeholders don't have GitLab access.
- Exporting the GitLab wiki into Confluence. You get two copies that drift apart.
A live view instead
With an app like GitLab for Confluence (made by our team), you add GitLab URLs to a page and they render as live previews, fetched each time the page is viewed:
- merge requests, issues and work items, and epics
- pipelines and jobs, with their current status
- releases and milestones
- commits, snippets and source files
For lists rather than single items, the GLQL query macro puts the results of a GitLab Query Language query (a supported subset of GLQL) into a table, for example merged MRs in project X with the label release-2.4.
There's also a Mermaid Gantt chart macro if you plan milestones in Confluence.
Self-managed GitLab: what you need
- Your GitLab instance must be reachable from the internet over HTTPS. Requests come from the app's fixed IP addresses, which are listed in the app settings, so you can allowlist them.
- Create a personal access token with the
read_api scope. OAuth is available for GitLab.com only. - Add the instance URL and token in the app settings. Then insert the GitLab Links macro and paste your URLs into it (automatic conversion on paste works for gitlab.com links). A Confluence site connects to one GitLab host at a time.
If your instance is only reachable on an internal network, you can allowlist those IP addresses in your firewall or expose the instance through a reverse proxy. Requests, including your token, go through the app's relay service, so involve your security team in that decision.
Summary
Need | Good fit |
|---|
Point to one MR | Plain link |
Show status that stays current | Live preview macro |
Lists of MRs or issues | GLQL table |
Self-managed GitLab | App with PAT connection over HTTPS |
What do you embed most from GitLab: MRs, pipelines, or files?
Further reading: Using GitLab macros, Installation and configuration