Confluence Readme Sync

This is a Github Action that uploads the README file (or any markdown file) in your repository to a Confluence page.

Contents

• Overview
• Setup
• Action Parameters
• Limitations
• Future Improvements

Overview

This is a Docker Github Action written in Python by @Gabesw that inserts the contents of a markdown file to a certain part of a Confluence page.

Setup

Getting Started

Create the .github/workflows/ directory structure in the root of your repository, if it does not exist, and create a file called confluence-readme-sync.yml with the following contents (filling the example parameters with the values listed here):

# .github/workflows/confluence-readme-sync.yml
on:
  push:
    branches:
      - master

jobs:
  dev:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - uses: gabesw/confluence-readme-sync@v1
        with:
          #filepath: relative/path/to/markdown.md #if commented, will use project's README.md
          url: https://<domain>/wiki/spaces/aSpace/pages/<page id>/<page name>
          username: [email protected]
          token: <Your Confluence API Token>
          insert_start_text: <p>start</p>
          insert_end_text: <p>end</p>

Authorizing the Confluence API

Log into Confluence and navigate to Manage Profile -> Security -> API Tokens. Create an API token and save the value.

Using Secrets (Reccomended)

Create secrets in your GitHub repository using this guide for any values you want to keep secure. You can use secrets in your confluence-readme-sync.yml file in the place of any value.

# .github/workflows/confluence-readme-sync.yml
# ...
token: {{ secrets.confluence_token }}

Action Parameters

Name	Description	Required	Default
filepath	The file path of the markdown file to sync, relative to the root of the repository	True	README.md
url	The full URL of the Confluence page to sync with, including the https://	True	---
username	The Confluence username with which to authenticate API calls. This should be an email address.	True	---
token	The Confluence token with wich to authenticate API calls. This token should be accessable and/or generated by the confluence user in username	True	---
insert_start_text	A piece of HTML in the body of the Confluence page after which the markdown contents will be inserted. You can find this by writing a piece of text or creating any element in confluence and then getting the HTML code of that element from the 'view source' or 'inspect element' feature in your browser. Make sure to grab the whole tag and not just the text inside, or the action will overwrite the closing tag. Eg. use <p>start text<p> instead of start text.	True	---
insert_end_text	A piece of HTML in the body of the Confluence page marking the end of the section in which the markdown content will be inserted. The same guidelines as insert_start_text apply for getting the full HTML snippet.	True	---

Limitations

• Images only work with external URL paths and not local files
• Code blocks with triple backticks must have a language
• Nested elements in lists will be flattened to the top level when the markdown is converted
• HTML inside of code blocks is encoded when it shouldn't be
• Section links need to be capitalized in confluence but need to be lowecase in markdown

Future Improvements

• Add support for local images by uploading them to an image hosting side or document hosting site such as Google Drive or an AWS S3 bucket or by directly uploading them to Confluence
• Allow code blocks with no language by mapping the language to None if not present
• Add postprocessor to decode the encoded HTML from code blocks with regex