February 2, 2025 - Patrick Kerwood
If you prefer keeping your documentation in Git, love writing in Markdown, but need to publish it in Confluence, Confluence Updater is the perfect solution. This tool allows you to set up a CI/CD pipeline that automatically converts Markdown to HTML and uploads it to Confluence Cloud whenever changes are made.
I created Confluence Updater (opens new window) to meet a requirement for delivering documentation in Confluence Cloud. As someone who enjoys writing in Markdown, including this very blog, and values GitOps as a single source of truth, I wanted a streamlined way to bridge the gap.
In this post, I’ll walk you through a few simple steps to achieve exactly that.
The first step is to create the required pages in Confluence at your desired location. Confluence Updater can only update existing pages, so you’ll need to set them up manually. Be sure to note the page ID, which you can find in the page's URL.
Next, in your repository, create a file named confluence-updater.yaml
with the configuration tailored to your needs.
Confluence Updater will read this file and update each Confluence page with its corresponding Markdown file.
If your Markdown file starts with an h1
header, Confluence Updater will automatically remove it and use it as the page title.
Alternatively, you can override the title using the overrideTitle
property, regardless, the h1
header will still be removed from the page.
pages:
- filePath: ./README.md
overrideTitle: My fancy documentation
pageId: <page-id>
labels:
- ci/cd
- filePath: ./docs/some-documentation.md
pageId: <page-id>
labels:
- ci/cd
If you're using GitHub Workflows, there's a GitHub Action available. Simply add the following action to your workflow file to use it.
- name: Confluence Updater
uses: kerwood/confluence-updater-action@v1
with:
fqdn: your-domain.atlassian.net
user: ${{ secrets.USER }}
api_token: ${{ secrets.API_TOKEN }}
Add your Atlassian username and API token as secrets on the repository.
See kerwood/confluence-updater-action (opens new window) for more details.
If you're not using Github, just add a step in your pipeline that downloads the latest or a specific version of
confluence-updater
and run it. Below example is for a Azure DevOps pipeline.
name: Confluence Updater
trigger:
branches:
include:
- master
paths:
include:
- README.md
- docs/*
pool:
vmImage: ubuntu-latest
steps:
- bash: |
curl -L https://github.com/Kerwood/confluence-updater/releases/latest/download/confluence-updater-x86_64-unknown-linux-musl -o confluence-updater
chmod +x confluence-updater
./confluence-updater -u $(CU_USER) -s $(CU_SECRET) --fqdn your-domain.atlassian.net
displayName: 'Update Confluence Page'
Add below variables to the pipeline, remember to set CU_SECRET
as a secret variable.
CU_USER
- Your confluence user.CU_SECRET
- Your API token which you can generate here. (opens new window)