The Live Table from GitLab macro displays an Excel, CSV, TSV, or JSON file from a GitLab repository as a table on a Confluence page. Paste the file URL directly into the page editor to create the macro automatically. The file can be in a public or private project, provided the person viewing the table has access to it.

Using the Live Table from GitLab macro

  1. In GitLab, open the file you want to display and copy its URL.
  2. Open a Confluence page for editing and paste the URL into the page editor. Confluence automatically converts it to the Live Table from GitLab macro. You can also type /Live Table from GitLab, select the macro, and paste the URL into its file URL field.
  3. Connect your GitLab account when prompted. Review the requested access and authorize the app.
  4. Choose the file-specific settings, if needed. The defaults automatically detect the file type, CSV delimiter, CSV quote character, and file encoding.
  5. Save the macro and publish the Confluence page.


Supported GitLab file URLs

Paste a GitLab file URL into the Confluence page editor to create the macro automatically. For example:

https://gitlab.com/GROUP/PROJECT/-/blob/main/data/report.csv

The macro also accepts a raw file URL:

https://gitlab.com/GROUP/PROJECT/-/raw/main/data/report.csv

Replace GROUP with the project namespace (including any subgroups), PROJECT with the project name, main with a branch, tag, or commit, and data/report.csv with the path to your file. The file can be Excel, CSV, TSV, or JSON.

The macro reads the file named in its configured URL when it renders the table. To display updates to a file, use a URL that points to a branch, such as main; a URL pinned to a commit refers to that particular version of the file. If the file is moved, renamed, deleted, or becomes inaccessible, update the URL or restore access.

File-specific settings

CSV and TSV files

  • Delimiter: Automatically detected by default. Specify it when the detected separator is incorrect.
  • Quote: Automatically detected by default. Specify the character used to quote values when detection is incorrect.
  • Encoding: Automatically detected by default. Select an encoding if the text is displayed incorrectly.
  • Data format: Choose Plain text, Wiki markup, or Markdown for the contents of cells.

JSON files

  • Path to node: Enter a path to the array or node whose data you want to display. You can enter several JSON paths, separated by commas. Leave it empty if the JSON document is an array at the root.
  • Expand all nested Objects: Expand nested object values in the output table.
  • Encoding: Automatically detected by default. Select an encoding if the text is displayed incorrectly.
  • Data format: Choose Plain text, Wiki markup, or Markdown for the contents of cells.


Viewing files from private projects

Each person viewing the table connects their own GitLab account and must have access to the project and file. Connecting the page author's account does not grant other viewers access. An administrator may need to allow the OAuth application if the GitLab instance restricts third-party applications.

The GitLab OAuth application requests the read_repository scope. GitLab defines it as read-only access to repositories in private projects through Git over HTTP or the Repository Files API. The macro uses the authorization to retrieve the file named in the configured URL. Review the scope on GitLab's authorization screen before connecting your account.

Working with the table

The table shows the file data available to the viewer when the macro loads. For filtering, charts, or other table processing, place the Live Table from GitLab macro inside Table Toolbox and combine it with the Table Filter, Charts & Spreadsheets macros.

Related information