Skip to content
    OpafraDocs

    Git sync

    Point Opafra at a repository and it imports plans, scripts and templates from it. Sync is one-way, and synced objects are read-only in the builder.

    View as MarkdownOpen in ClaudeOpen in ChatGPT

    A git source points Opafra at a repository and branch. On each sync, Opafra reads plans, scripts and config templates from it and creates or updates them in your workspace.

    Sync is one-way: Opafra reads from git and never writes back. That is what makes the repository the single source of truth rather than one of two.

    Why sync at all#

    Keeping plans in git means changes go through review before they reach production, the history of what changed is the repository's history, and a plan can be reverted the way code is.

    A plan owned by a repository is read-only in the builder. Edits go through a pull request and arrive on the next sync, which is the property that makes the review real rather than advisory.

    Connect a repository#

    Choose the repository, the branch, and how Opafra authenticates:

    AuthUse it when
    PublicThe repository needs no credential
    TokenA personal access token, stored encrypted
    GitHub AppPreferred. Clone credentials are minted fresh at clone time rather than stored

    The GitHub App path is better where it is available: there is no long-lived token at rest, because an installation token is minted for each clone and expires on its own.

    Layout#

    Opafra looks in three directories, relative to an optional base path:

    plans/        plans
scripts/      shell scripts a plan can upload and run
templates/    config templates

    Those defaults follow the convention most teams already use. Any of them can be changed, and blanking one stops that kind being synced at all.

    Sync modes#

    ModeBehaviour
    ManualSyncs when you ask it to
    WebhookThe repository notifies Opafra on push, and it syncs immediately
    PollOpafra checks periodically

    Webhook is the right default for an active repository: changes land quickly and nothing is polled that has not changed. The webhook is authenticated with a shared secret, so an unsigned request cannot trigger a sync.

    What a sync does#

    Each file is hashed. A file whose hash is unchanged is skipped, so a sync where nothing moved is a no-op rather than a rewrite of every object.

    The result reports how many objects were created, updated and removed, plus any files that failed to parse. The commit that was synced is recorded, so you can tell exactly which revision of the repository your workspace reflects.

    Deleted files#

    A file removed from the repository does not delete the object. It is marked orphaned.

    That is deliberate. A branch mistake, a bad merge or a mistyped path would otherwise silently remove working automation, and a deletion is much harder to notice than an orphan flag. Restoring the file un-orphans the object on the next sync; deleting it for real is a decision you make in Opafra.

    Grouping#

    A synced plan can carry a group, which files it into a collection. You can also file one by hand, and a manual filing is pinned so re-syncs do not overwrite it unless the file's own group changes.

    Grouping and git source are independent axes: where a plan came from and how it is organised are different questions.

    What is recorded#

    Connections, sources, every sync, and webhook enable and disable are all written to the audit log, including which commit a sync brought in.

    Next steps#