GitLab for Confluence
GitLab for Confluence
Breadcrumbs

How to use each GitLab Macro

GitLab for Confluence offers a range of useful macros that let you seamlessly integrate GitLab information into your Confluence pages.

n this section, you'll find instructions on how to use each GitLab macro effectively within Confluence.

Viewing issues

Gitlab Issue Macro

The Gitlab Issue macro allows you to display a single issue.

image-20250617-225459.png

  1. Enter the Base URL

  2. Select which Project to display the issue from

  3. Use the Issue text search to search for an issue
    or
    Use the Gitlab Issue ID field to enter the Issue ID number

  4. Enable Show description to display the description of the issue

  5. Enable Show comments to display any comments associated with the issue

  6. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Issues List Macro

The Gitlab Issues list macro allows you to display a list of macros with a project filtered by status or label.

image-20250617-231536.png

  1. Enter the Base URL

  2. Select which Project to display the issue from

  3. Choose with the State of the issues to be displayed e.g. Opened or Closed

  4. If you wish to filter by label, add them here

  5. Enable Show description to display any description present below each issue

  6. Use Order by to choose if the list is ordered based on when it was created or last updated

  7. Choose if the list is in Ascending or Descending order using the Sort direction field

  8. Choose the Maximum numbers of entries to fetch, however please note that more than 100 entries will result in multiple api calls

  9. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Issues Gantt Chart Macro

image-20260421-002159.png

  1. Enter the Base URL

  2. Select which Project to display information for

  3. Choose whether or not you wish to display issues from a Milestone

  4. From Date lets you show issues created after the selected date

  5. To Date lets you show issues created before the selected date

  6. Choose the Maximum Entries to display (10, 20, 50, 100, 200 or 300)

  7. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro

Viewing Projects

Gitlab Project Macro

The Gitlab Project macro allows you to display detailed information about a Gitlab project.

image-20250617-233839.png

  1. Enter the Base URL

  2. Select which Project to display information for

  3. Choose whether or not to Show details of the project

  4. Show latest build status of the project if given will display build status where available

  5. Choose whether or not to Show branches

  6. Choose whether or not to Show releases

  7. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Projects List Macro

The Gitlab Projects list macro allows you to display detailed information about multiple Gitlab projects.

image-20250617-234644.png

  1. Enter the Base URL

  2. Select which Group to display Project information for

  3. Use the Projects count field to limit how many projects will be displayed

  4. Choose whether or not to Show details of the project

  5. Show latest build status of the project if given will display build status where available

  6. Choose whether or not to Show branches

  7. Choose whether or not to Show releases

  8. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Viewing Gitlab Groups

Gitlab Groups List Macro

The Gitlab Groups list macro allows you to display Gitlab groups in Confluence

image-20250618-011552.png

  1. Enter the Base URL

  2. Specify which Group you wish to see or select None

  3. Groups count allows you to limit how many groups are displayed

  4. Show only direct groups will prevent additional tiers of sub groups from displaying

  5. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Epic Macro

The Gitlab Epic macro allows you to provide an overview of Gitlab Epics.

image-20250620-020012.png

  1. Enter the Base URL

  2. Specify the Group with the Epic you wish to display

  3. Choose the Epic to be displayed

  4. Specifying the Maximum numbers of entries to fetch limits the amount of items displayed for each Epic

Viewing Development Activities

Gitlab Commit Macro

The Gitlab Commit macro allows you to display information pertaining to commits made in Gitlab

image-20250618-000103.png

  1. Enter the Base URL

  2. Select the Project of the commit you wish to display the information for

  3. Enter the Commit hash of the relevant commit

  4. Choose to Show files associated with the commit

  5. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Merge Request List Macro

The Gitlab Merge Requests list macro allows you to keep track of active merge requests by display them in Confluence

image-20250618-000804.png

  1. Enter the Base URL

  2. Select which Project to display the merge requests for

  3. Choose whether or not to Show merged requests

  4. Choose whether or not to Show closed merge requests

  5. Use the Show description option if you wish to display the description of merge requests

  6. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Builds Macro

The Gitlab Builds macro allows you to display a list of all builds associated with a Gitlab Project

image-20250618-001704.png

  1. Enter the Base URL

  2. Select which Project to display the builds for

  3. The maxitemsShown option allows you to limit how many builds are displayed

  4. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Release Macro

The Gitlab Release macro allows you to display previous releases and their associated merge requests and commits

image-20250618-002104.png

  1. Enter the Base URL

  2. Select which Project to display the releases for

  3. Search for a specific release using the Tag search or leave it as The latest to display the most recent release

  4. Choose whether or not to Show Merge Requests

  5. Choose whether or not to Show Commits

  6. Use the Commits count field to limit how many commits are displayed

  7. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Viewing File Content and Code

Gitlab File Content Macro

The Gitlab File content macro allows you to display file content from your Gitlab repositories in Confluence

image-20250618-004714.png

  1. Enter the Base URL

  2. Select which Project to display file content from

  3. Use the Path to file to link to your chosen Gitlab file

  4. Use the Reference name to reference a specific branch, tag or commit

  5. The File type selection allows you to chose how the information is rendered

  6. The Show only content option allows you to remove the border and header

  7. The Hide content by default option will initially present the information minimized, with the option to click the Show button to expand the file content

  8. Display file name allows you to override the default file name

  9. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Snippet Macro

The Gitlab Snippet macro allows you to display Gitlab snippets in Confluence

image-20250618-005656.png

  1. Enter the Base URL

  2. Use snippet ID allows you to link to snippet based on its numerical ID. Note: this will remove the Project and Snippet title options

  3. Select which Project to display the snippet for

  4. Provide the Snippet title of the relevant snippet

  5. Use the Show description option to display the description of the associated snippet

  6. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Viewing GitLab Milestones

Gitlab Milestone Macro

The Gitlab Milestone Macro allows you to display individual milestones in Confluence

image-20250926-221226.png

  1. Enter the Base URL

  2. Select which Project to display file content from

  3. Select the Milestone from the drop down list, using the search bar to filter if necessary

  4. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Gitlab Milestones Macro

The Gitlab Milestones macro allows you to display multiple milestones in Confluence

image-20250618-012541.png

  1. Enter the Base URL

  2. Select which Project to display file content from

  3. The State option allows you to choose the status of the Milestones e.g. active or closed

  4. Search by text allows you to limit the milestones to those that match the text field

  5. Maximum numbers of entries to fetch allows you to limit how many results are displayed

  6. Use the refresh button to see a preview of what will be displayed once the Confluence page is published/updated then click Insert to enter the macro


Need to Integrate GitLab and Jira Data Center? Check out Jigit - GitLab integration for Jira


Updated: