November 16, 2021 - Patrick Kerwood
If you like to keep your documentation in Git, love writing in markdown but are somehow required to deliver documentation in Confluence, look no further. With Confluence Updater you can build a CI/CD pipeline to render a markdown page to html on change and upload it to Confluence Cloud.
Confluence Updater is a tool I created in Rust because I had a requirement to deliver documentation in Confluence Cloud. I love writing in markdown, even this blog I do in markdown, and I'm a big fan of GitOps and the idea of using Git as a single source of truth.
In this blog post I will show the few easy steps to do exacly that. I will be using Azure DevOps (God forbid), but any CI/CD pipeline will do.
The first step is to create the actual pages in Confluence, in the location you want. Confluence Updater can only update an existing page. Write down the page ID, you will find it in the URL of the page.
In your repository, create a file named
confluence-config.yaml with below content. Confluence Updater will read this file and .... well it's pretty self explanatory, have a look at it.
You will need to add an entry for each file you want to update.
content: - filePath: './README.md' title: My fancy documentation pageId: '<page-id>' contentType: page labels: - ci/cd - filePath: './docs/some-documentation.md' title: My fancy documentation pageId: '<page-id>' contentType: page labels: - ci/cd
Next create a file named
azure-pipelines.yml and add below yaml code to it. The logic is very simple, when ever a change is commited to
README.md or any file in the
docs folder, the pipeline will run.
Change the version number in the
curl command to fit the newest version.
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/download/v1.0.0/confluence-updater-x86_64-unknown-linux-musl -o confluence-updater chmod +x confluence-updater ./confluence-updater update -u $(CU_USER) -s $(CU_SECRET) --fqdn $(CU_FQDN) displayName: 'Update Confluence Page'
Commit the changes and push it to the repository. In Azure DevOps, press the
Set up build button to create the new pipeline.
Confluence Updater needs some parameters to run. Add below variables to the pipeline by pressing the
Variables button, 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)
CU_FQDN- The FQDN to your Confluence Cloud instance eg.
Save your pipeline and run it.