From 89bc9c6a3c5986d60e1c35935514000f83357476 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 23 Jul 2026 13:12:22 -0700 Subject: [PATCH 1/3] docs: add a GitHub Actions section for publishing to Confluence Document running markfluence in CI to keep Confluence pages in sync with repo markdown: credentials via secrets/variables, a push-triggered workflow that installs from source (go install) and runs `update`, and notes on --force, exit codes, and write permissions. Links to the reusable-action tracking issue (#29). --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/README.md b/README.md index 8eb1259..fa9bce5 100644 --- a/README.md +++ b/README.md @@ -272,6 +272,80 @@ Errors and exit codes: - Error `code` values: `CONFIG`, `AUTH`, `NOT_FOUND`, `VALIDATION`, `CONVERT`, `IO`, `NETWORK`, `API`. +## GitHub Actions + +markfluence runs well in CI to keep Confluence pages in sync with markdown in your +repo: on a push to your default branch, publish the changed docs. Each page needs +a `page_id` in its frontmatter (from a prior `create`, or `markfluence fix`), since +`update` publishes to existing pages. + +### Credentials + +Store the API token as an [encrypted secret][secrets] (never commit it); the base +URL and username can be repository **variables** or secrets. markfluence reads them +straight from the environment — no `.env` needed in CI. + +- `CONFLUENCE_TOKEN` — secret (required). +- `CONFLUENCE_URL`, `CONFLUENCE_USERNAME` — variables or secrets. + +[secrets]: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions + +### Workflow + +```yaml +name: Publish docs to Confluence + +on: + push: + branches: [main] + paths: ['docs/**.md'] # only when docs change + +# Avoid overlapping publishes racing on the same pages. +concurrency: + group: confluence-publish + cancel-in-progress: false + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-go@v5 + with: + go-version: '1.25' + + # No release binaries are published yet, so install from source. Pin a tag + # (…@v1.2.3) once releases exist, rather than @latest, for reproducibility. + - name: Install markfluence + run: go install github.com/mozilla/markfluence@latest + + - name: Publish + env: + CONFLUENCE_URL: ${{ vars.CONFLUENCE_URL }} + CONFLUENCE_USERNAME: ${{ vars.CONFLUENCE_USERNAME }} + CONFLUENCE_TOKEN: ${{ secrets.CONFLUENCE_TOKEN }} + run: markfluence update docs/**/*.md --force +``` + +Notes: + +- **`--force`.** A fresh checkout gives every file a current mtime, so markfluence's + "skip unchanged" heuristic (file mtime vs. the page's last-version time) would + publish everything anyway. `--force` makes that explicit. To publish only the + files that actually changed in the push, compute the changed set (e.g. with + `git diff --name-only`) and pass those paths instead. +- **Exit codes.** `update` exits non-zero if any file fails, so the job fails + loudly. Add `--json` to get machine-readable per-file results on stdout (see + [`--json` output](#--json-output)) if a later step needs to parse them. +- **Enable Actions to write, if persisting.** `update` never writes back to files, + but `create` does (it records `page_id` etc.). If a workflow runs `create` and + commits the result, give the job `permissions: contents: write` and a commit + step; most publish workflows use `update` and need no write permission. + +A reusable composite/Docker action wrapping this is tracked in +[#29](https://github.com/mozilla/markfluence/issues/29). + ## Markdown page structure Each Markdown file is one Confluence page: an optional YAML **frontmatter** block From ead7465c97efb8a6031fd33d02314e5e1722f024 Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 23 Jul 2026 13:19:58 -0700 Subject: [PATCH 2/3] docs: simplify the GitHub Actions section Store all three settings as secrets, use a single-document publish example with an explicit --page-id, and trim the notes to the essentials. --- README.md | 33 ++++++++++++--------------------- 1 file changed, 12 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index fa9bce5..584b931 100644 --- a/README.md +++ b/README.md @@ -274,19 +274,18 @@ Errors and exit codes: ## GitHub Actions -markfluence runs well in CI to keep Confluence pages in sync with markdown in your -repo: on a push to your default branch, publish the changed docs. Each page needs -a `page_id` in its frontmatter (from a prior `create`, or `markfluence fix`), since -`update` publishes to existing pages. +markfluence can run in CI to keep Confluence pages in sync with markdown in +your repo: on a push to your default branch, publish the changed docs. You +will need to know the Confluence `page_id` for each page you want to update. ### Credentials -Store the API token as an [encrypted secret][secrets] (never commit it); the base -URL and username can be repository **variables** or secrets. markfluence reads them -straight from the environment — no `.env` needed in CI. +Store environment variables as [encrypted secret][secrets] (never commit them). +markfluence reads them straight from the environment — no `.env` in CI. -- `CONFLUENCE_TOKEN` — secret (required). -- `CONFLUENCE_URL`, `CONFLUENCE_USERNAME` — variables or secrets. +- `CONFLUENCE_TOKEN` +- `CONFLUENCE_URL` +- `CONFLUENCE_USERNAME` [secrets]: https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions @@ -322,26 +321,18 @@ jobs: - name: Publish env: - CONFLUENCE_URL: ${{ vars.CONFLUENCE_URL }} - CONFLUENCE_USERNAME: ${{ vars.CONFLUENCE_USERNAME }} + CONFLUENCE_URL: ${{ secrets.CONFLUENCE_URL }} + CONFLUENCE_USERNAME: ${{ secrets.CONFLUENCE_USERNAME }} CONFLUENCE_TOKEN: ${{ secrets.CONFLUENCE_TOKEN }} - run: markfluence update docs/**/*.md --force + run: + markfluence update --page-id=12345 --force docs/some_doc.md ``` Notes: -- **`--force`.** A fresh checkout gives every file a current mtime, so markfluence's - "skip unchanged" heuristic (file mtime vs. the page's last-version time) would - publish everything anyway. `--force` makes that explicit. To publish only the - files that actually changed in the push, compute the changed set (e.g. with - `git diff --name-only`) and pass those paths instead. - **Exit codes.** `update` exits non-zero if any file fails, so the job fails loudly. Add `--json` to get machine-readable per-file results on stdout (see [`--json` output](#--json-output)) if a later step needs to parse them. -- **Enable Actions to write, if persisting.** `update` never writes back to files, - but `create` does (it records `page_id` etc.). If a workflow runs `create` and - commits the result, give the job `permissions: contents: write` and a commit - step; most publish workflows use `update` and need no write permission. A reusable composite/Docker action wrapping this is tracked in [#29](https://github.com/mozilla/markfluence/issues/29). From 022feb21e5e070eabd6ff215ea7f5a747a2eb8ae Mon Sep 17 00:00:00 2001 From: Will Kahn-Greene Date: Thu, 23 Jul 2026 13:22:32 -0700 Subject: [PATCH 3/3] docs: update the markfluence-version token format Reflect the new build stamp (markfluence VERSION (SHA, DATE)) that landed in #45; note it matches `markfluence --version`. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 584b931..2445a7e 100644 --- a/README.md +++ b/README.md @@ -428,7 +428,8 @@ URL; **heading anchors** are rewritten to Confluence's anchor scheme. **Comment directives:** - `` — table-of-contents macro. - `` — replaced with the build stamp, - `markfluence vVERSION COMMITDATE`. + `markfluence VERSION (SHA, DATE)` (the same string `markfluence --version` + prints). **Raw Confluence storage format.** You can paste Confluence [storage format](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html)