mdBoard

Mirroring to a public repository

mdboard mirror publishes a clean snapshot of a private checkout to a public repository. It is a pre-processed push, not a raw git push.

Typical use:

private: github.com/example/private-mdboard
public:  github.com/example/public-mdboard

The private board lives in .mdboard/. The public mirror must not contain it.

Before the first run

mdboard init creates a default .mdboardignore unless one already exists.

.mdboard/
.mdboardignore
.env
.env.*
*.pem
*.key
*.p12
.DS_Store
.idea/
.vscode/

Mandatory exclusions:

  • .git/
  • .mdboard/
  • .mdboardignore

Add project-specific patterns as needed. Prefer card attachments over new special directories.

Profiles

Profiles live in .mdboard/mirror.toml:

[profiles.public]
to = "git@github.com:example/public-mdboard.git"
branch = "main"
ignore = ".mdboardignore"
keep_public = ["README.public.md", "docs/public/**"]

[[precautions]]
id = "MP-0001"
title = "Customer exports"
text = "Never publish files under exports/customers/."
profiles = ["public"]
status = "active"

Run a named profile:

mdboard --actor agent mirror --profile public --dry-run
mdboard --actor agent mirror --profile public --push --confirm-first-push

--to and --branch override the profile for one run.

Branch restriction

The command runs only from the configured [git] nightly or [git] stable branch, and only with a clean working tree. It uses the committed tree, never uncommitted files.

Dry run

--dry-run prints:

  • the profile and source branch;
  • the target;
  • included and excluded files;
  • applicable precautions;
  • secret findings.

No target is written and nothing is pushed.

Secret scanning

The built-in scanner is mandatory. It checks:

  • sensitive filenames such as .env, .pem, .key, .p12;
  • content markers such as private keys, API secrets and passwords.

A finding stops the mirror. .mdboardignore is a deterministic exclusion mechanism, not a secret scanner; a secret in an included file is still copied.

Precautions

Precautions are persistent, profile-scoped instructions. They are separate from .mdboardignore and separate from standing orders.

They are printed during the dry run. If an agent cannot verify a precaution automatically, it must ask before pushing.

Target update

The public target keeps its own sanitized history:

  • the target is cloned;
  • its tree is replaced with the sanitized snapshot;
  • files no longer present in the source are removed;
  • keep_public entries are preserved;
  • a mirror commit is created;
  • the branch is pushed.

The first push requires --confirm-first-push after manual review.

--force is explicit and should be rare.

Commands

mdboard mirror --profile public --dry-run
mdboard mirror --profile public --push --confirm-first-push
mdboard mirror --to <url> --branch main --dry-run

Limits

  • Snapshot mirroring only; private Git history is never copied.
  • Tags are not yet mirrored.
  • The built-in scanner is pattern-based; it is not a replacement for a dedicated secret scanner.
  • The public target must be reviewed after the first push and after sensitive changes.