The Live Table from GitHub macro displays an Excel, CSV, TSV, or JSON file from a GitHub 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 repository, provided the person viewing the table has access to it.


Using the Live Table from GitHub macro

  1. In GitHub, 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 GitHub macro. You can also type /Live Table from GitHub, select the macro, and paste the URL into its file URL field.
  3. Connect your GitHub 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 GitHub file URLs

Paste a GitHub file URL into the Confluence page editor to create the macro automatically. For example: https://github.com/OWNER/REPOSITORY/blob/main/data/report.csv.

The macro also accepts raw file URLs in either form:

Replace OWNER, REPOSITORY, BRANCH_OR_COMMIT, and path/to/file.csv with the values for 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 you move, rename, delete, or make the file 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 repositories

Each person viewing the table connects their own GitHub account and must have access to the repository and file. Connecting the page author's account does not grant other viewers access. If an organization restricts OAuth apps, an organization owner may need to approve the app before its members can use it with the organization's repositories.

The GitHub OAuth app requests the repo scope to access private repository content. GitHub defines this as a broad scope that also grants write access to repositories, although this macro uses the authorization to read the file named in the configured URL. Review the scope on GitHub'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 GitHub macro inside Table Toolbox and combine it with the Table Filter, Charts & Spreadsheets macros.

Related information