gitfluence

Sync markdown files from any git repo working tree to Confluence as a page hierarchy.

Uses mdfluence for markdown → Confluence conversion and upload. All mdfluence CLI options can be passed through gitfluence.

Installation

pip install gitfluence

Usage

gitfluence <repo-path>                   # auto-detect prod vs int
gitfluence --dry-run <repo-path>         # preview, no API calls
gitfluence --space MYSPACE .             # override space
gitfluence --prefix "DEV" .              # override auto-prefix
gitfluence --beautify-folders .          # pass mdfluence options

Environment Variables

* On --dry-run, missing host defaults to https://dummy.example.com/api, missing tokens default to dummy and missing space defaults to DRY_RUN. In interactive mode, missing values are prompted.

Auth decision (per target): token > username+password > prompt > dry-run dummy.

cp setenv.example.sh setenv.sh

source setenv.sh

Copy-Item setenv.example.ps1 setenv.ps1

. .\setenv.ps1

Prod vs Integration Logic

Page Hierarchy

All root-level pages from the repo are created as children of the Confluence space's home page. Subdirectories become nested child pages.

In integration mode (feature branches), the following hierarchy is created:

Space Homepage
  └── {repo-name}              (integration root)
       └── Branch: {branch}    (branch grouping page)
            └── Page Title     (content pages)
                 └── Sub Page

• Integration root — an empty page named after the repository directory, created under the space homepage. Deleting it removes all integration artifacts.
• Branch page — an empty page titled Branch: {branch-name} under the integration root. Groups all content pages for that branch. Each branch gets its own grouping page.
• Content pages — the actual documentation pages, created as children of the branch page with clean titles (no branch prefix).

GitHub Action

Consumer repos can integrate using the composite action:

name: Sync to Confluence

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: geopanther/gitfluence@main
        with:
          repo_path: "."
          extra_args: "--beautify-folders"
          confluence_host: ${{ secrets.CONFLUENCE_HOST }}
          confluence_token: ${{ secrets.CONFLUENCE_TOKEN }}
          confluence_space: ${{ secrets.CONFLUENCE_SPACE }}

Action inputs

CLI Options

gitfluence-specific options

These options are not available in mdfluence:

Note: --page-id is not supported. Pages are managed by directory hierarchy. Use --parent-id to anchor pages under a specific parent.

Differences from mdfluence defaults

gitfluence changes the following mdfluence defaults to be enabled by default:

Preface and postface behave differently from mdfluence:

• mdfluence: --preface-markdown / --postface-markdown accept an optional value; when given without a value they default to a static "Contents are auto-generated, do not edit." message. No template placeholders.
• gitfluence: Both always require a value. All preface/postface sources (CLI string, file, and bundled defaults) support {branch_name}, {repo_origin}, {username}, {hostname}, {timestamp} template placeholders. Bundled defaults are richer (repo origin, branch, author, timestamp).

mdfluence pass-through options

All remaining mdfluence options are passed through unchanged:

Login: --host / -o, --token, --username / -u, --password / -p, --insecure

Page information: --title, --content-type (choices: page/blogpost), --message, --minor-edit, --strip-top-header, --remove-text-newlines, --replace-all-labels

Parent selection (mutually exclusive): --parent-title / --parent-id / --top-level

Preface (mutually exclusive): --preface-markdown / --preface-file / --no-preface

By default a "DO NOT EDIT" banner with repo origin and branch name is prepended. All preface sources support {branch_name}, {repo_origin}, {username}, {hostname}, {timestamp} placeholders.

Postface (mutually exclusive): --postface-markdown / --postface-file / --no-postface

By default a metadata footer with repo origin, branch, author and timestamp is appended. All postface sources support the same placeholders as preface.

Directory: --collapse-single-pages, --no-gitignore, --skip-subtrees-wo-markdown

Directory titles (mutually exclusive): --beautify-folders / --use-pages-file

Empty dirs (mutually exclusive): --collapse-empty / --skip-empty

Relative links: --enable-relative-links, --ignore-relative-link-errors

Anchors: --convert-anchors / --no-convert-anchors

General: --only-changed, --max-retries

Development

See CONTRIBUTING.md for development setup and guidelines.

License

MIT