Docs / Optional Git Synchronization

Your browser workspace, connected to your repository

Keep editing maps in Monaco and reviewing changes in the workspace. Connect an external repository when you want the same applied configuration alongside the rest of your engineering work. You do not need to switch to a local editor or install a CLI.

External Git is optional. Configuration history is already part of your workspace.

Connections, partners, maps, and any published scenario definitions and applied bindings share one configuration apply process. A repository is another way to work with that configuration, not a separate processing engine.

Three states that are easy to confuse

Saved draft: Your browser editing work is retained. It may be incomplete or invalid. It is not necessarily live, and external Git does not mirror every keystroke or all saved sample files.
Applied configuration: You reviewed and confirmed a configuration change, or an authorized repository/API change passed the same apply checks. Runtime activation may still be pending; inspect Change history before assuming new traffic uses it.
Synchronized repository: The external copy has caught up with the applied configuration. Synchronization runs about every 30 seconds, not instantly. It can pause on a conflict or credential problem while your workspace remains available.

See changes without reloading your workspace

The Mapper checks your shared draft while you work. If another member saved it, Shared draft changed pauses cloud autosave and keeps your open files. Choose Reload shared to replace them with the shared draft, or Save as copy to keep your work separately. This is distinct from a repository change to applied configuration, which follows the existing conflict-aware configuration reconciliation.

Change history checks for new changes and publication updates about every 10 seconds while you view it. The expanded External repository panel checks connection and synchronization status on the same cadence, including a connection made elsewhere. Returning to the tab or reconnecting also checks for updates. These browser checks display server state; they do not trigger a Git synchronization or apply configuration themselves.

Changes from another member, the API, or your repository can appear while you keep working. Your selected history entry stays selected, older pages remain available, and unsaved Mapper edits are protected by the editor's existing conflict handling. Partner, notification, and member settings pause the relevant refresh while you edit, rather than replacing your draft. A failed check keeps last-known data visible with an error or warning and retries automatically.

A review stays the review you opened. Deployment and recovery plans stay pinned; their test-result status updates and retries failed reads automatically, without rerunning tests or approving a change. If configuration changes underneath a review, the normal apply checks require a fresh review. An interrupted apply still needs its explicit retry action. In Live maps → Configuration history, your selected historical version stays selected while the clearly labeled current-live side of its comparison updates when a newer version appears.

Your signed-in Mapper also rechecks workspace access and renews the existing session. A permission change or unavailable session can make the editor read-only without throwing away the open draft. The sidebar checks lightweight status and configuration data about every minute; detailed partner traffic checks run in the relevant views.

Optional: edit partner and AS2 configuration as files

The partner forms remain the simplest way to get started. If you prefer files, open the signed-in Mapper's Explorer, expand Advanced configuration, and choose Partner configuration files. Select an existing partner or AS2 connection. The editor includes JSON completion and validation, plus the same reviewed apply used by the forms. You do not need a connected repository or a scenario.

A partner describes the business relationship, including X12 identifiers and its mapping association. An AS2 connection describes transport: AS2 identifiers, endpoints, algorithms, and the partner's public certificates for Production and optional Test traffic. Several partners can share one connection, for example through a VAN. The files preserve that shared connection rather than duplicating it under every partner.

partners/<partner-key>/partner.json
as2-connections/<connection-key>/connection.json
as2-connections/<connection-key>/certificates/production.pem
as2-connections/<connection-key>/certificates/test.pem
mappings/<mapping-key>/mapping.json
mappings/<mapping-key>/source.x12mapper

These are the same portable files used by configuration export and Git. Keep their resource keys stable. partner.json refers to its connection through spec.as2ConnectionKey; mapping.json refers to its partner through spec.partnerKey. Each connection environment references its public certificate using publicCertificatePath, relative to connection.json. No Test setup is required: spec.environments.test can be null.

Production and Test can share one certificate file. Both environments can set publicCertificatePath to ./certificates/shared.pem, or to the same existing file such as ./certificates/production.pem. Replacing that file updates both certificates through normal review and apply; their AS2 identifiers, endpoints, and other settings remain independent. Exports use one shared.pem when the certificates are identical, otherwise the two files shown above. Other file names may use 1–64 lowercase letters, digits, hyphens or underscores, starting with a letter or digit. References cannot leave the connection's certificates directory or use subdirectories or URLs.

Edit the JSON or load a public PEM certificate.Choose a certificate file to upload replacement public material. With both environments configured, choose “Use this certificate for Production and Test” to share the selected file and remove unused certificate files from the draft. Review shows the environments using each certificate, its fingerprint, validity dates, and the partners sharing the connection. To remove Test configuration, set its environment to null and remove its certificate file only if Production does not use it. Adding or sharing a certificate file alone does not enable Test; its connection settings must also be complete.
Save a draft, or review the change.Save draft in this browser stores these configuration-file edits locally in this browser, not in the shared Mapper draft or Git. Drafts do not change live traffic. A newer applied version or a removed resource leaves your draft intact but prevents it from overwriting newer settings.
Review, then explicitly confirm.Inspect the exact normalized file changes, affected conversations, and validation results. Confirmation uses the existing atomic configuration apply, Change history, runtime publication, and optional external Git synchronization. It does not send a document or run a scenario. Read-only members can inspect files but cannot review or apply changes.

Only public certificates belong here. Use a single PEM X.509 certificate per file, not a chain, private key, or PKCS#12/PFX archive. ModernEDI's local signing/decryption credentials remain managed secrets referenced by configuration; passwords and tokens must never be committed. Public certificate files are normalized to LF line endings and 64-column base64. The editor, automatic Git import, and configuration runner derive certificate and manifest hashes; you do not calculate them by hand.

JSON is the supported configuration format; YAML is not supported. Inline publicCertificatePem remains a valid alternative to a file reference, but an environment cannot use both. Exports prefer separate files. Moving identical public certificate material between those representations does not change transport settings or invalidate conversation bindings; changing the certificate itself does. Exact reviewed files and verification identities remain pinned.

For local editor tooling, use the generated partner JSON Schema and AS2 connection JSON Schema. They come from the same structured contract as the API and embedded editor. The server additionally checks workspace-owned references, certificate contents, supported destinations, and dependencies. If you add or remove files directly in Git, update modernedi.json's explicit inventories too.

Recover a saved configuration without rewriting history

You do not need an external repository or Git knowledge to recover a configuration. A workspace member with permission to operate configuration can open Change history, select an earlier change, and choose Review recovery.

Compare the entire saved version with the current workspace.The review lists additions, changes, and removals, including map source and scenario changes. It is not an undo of only the selected change: later edits can be replaced, and resources added afterward can be removed. Nothing changes while you review.
Optionally require fresh saved mapping tests.The server runs the cases in the selected version against the exact proposed configuration. The same aggregate limits apply: 25 tested mappings and 100 cases. Mappings without saved cases are explicitly untested. Old mapping or scenario passes are historical evidence, not approval for this recovery.
Confirm the changes and apply reviewed recovery.ModernEDI rechecks the current configuration, dependencies, and exact plan. If the workspace changed, prepare another review. If a response is interrupted, use Retry apply to check the same request safely rather than starting another recovery.
Check publication and, if connected, synchronization.Recovery creates a new configuration change and Git commit linked to its source version. Runtime publication can remain pending and retry automatically. External Git receives this new change through normal synchronization; concurrent repository edits can still cause a conflict.

Configuration recovery is not a workspace or data reset.

It preserves change history, mapping revisions, Git history, transactions, and scenario runs. It does not resend documents, restore secret values, change access or billing, or overwrite unsaved Mapper drafts. Missing credentials, incompatible syntax trees, immutable definition conflicts, and affected active runs still block recovery. Recovered scenario bindings use current resolved dependencies and new revisions where needed; verify those conversations again when you want new runtime evidence.

Connect once, as the workspace owner

Choose a configuration-focused private repository.ModernEDI supports authenticated HTTPS Git, not just GitHub. Choose the exact branch and a dedicated directory such as modernedi/. Repository size and transfer limits also cover files outside that directory.
Create a repository access token with your provider.This is not a ModernEDI API key. Restrict it to the intended repository, allow the required read/write Git operations, and set an expiry. Follow the provider-specific GitHub, GitLab, Bitbucket, and other-provider instructions for the right permissions and username.
Open Change history → External repository.Enter the repository URL, branch, directory, Git username, and token. Never put the token in the URL or in a committed file. ModernEDI stores it as an encrypted workspace secret and does not return it to the browser.
Inspect the first synchronization.Compare any existing workspace and repository configuration before resolving a conflict. Do not choose a side blindly. Only the configured directory is managed, and ModernEDI never force-pushes.

The connected branch can change live workspace configuration.

Use branch permissions appropriate to your team. The sync credential must be allowed to push under those rules. Synchronization is not itself a pull-request approval workflow or a guarantee that a change was reviewed by another person.

Try one browser change

Edit a map as a draft, run a sample, review the change, and deploy it. Wait for runtime activation, then check the external repository status. After successful synchronization, the repository contains the applied map source and its portable configuration. Merely saving the draft does not publish it.

Applied scenario files work the same way. In Git, a resource envelope carries the complete authored scenario under spec.source. Bindings use stable partner and mapping resource keys rather than another workspace's numeric IDs. Omitted syntax-tree choices stay omitted in source even though an applied runtime revision has resolved exact dependencies.

Try one repository change

Make a small, deliberate edit to an existing mapping source in the configured directory and commit it to the connected branch through your team's normal review process. If only the repository changed, ModernEDI prepares a configuration plan and applies it through the same validation and concurrency checks used by browser changes.

Inspect Change history for the result. Mapper refreshes applied configuration, but it preserves an editing draft that conflicts with the incoming change. Resolve that draft conflict before publishing another edit; a refresh is not permission to discard your work.

Do not hand-edit checksums after an ordinary source edit: synchronization prepares them. Preserve resource keys and paths. Adding or removing files also requires updating the explicit modernedi.json inventory. See the bundle contract before changing resource membership.

Optional: test repository changes before they go live

In Change history → External repository, the workspace owner can enable Run saved mapping cases before importing repository changes. It is off by default. You do not need Git, saved tests, or scenarios to process documents with your partner mappings.

For example, suppose an incoming 850 map has a saved case that expects three order lines. A repository edit accidentally emits only two. With this setting enabled, ModernEDI runs the incoming map and its saved cases before applying the repository configuration. The mismatch holds the entire import; the currently applied maps, partners, and scenario bindings remain unchanged.

Save useful cases with your maps.Use Saved test cases in Mapper, then apply them so they enter configuration and Git history. All saved cases in the incoming configuration are tested, including unchanged maps with cases. Mappings without cases are explicitly untested.
Enable the optional check.It protects future repository-to-workspace imports, including an explicit Use repository conflict choice. Browser-to-repository synchronization is unchanged. Enabling it does not retest already synchronized configuration.
Inspect the result in External repository.The panel shows the tested commit, case outcomes, and downloadable evidence. A passing result is tied to the exact incoming bundle, plan, workspace snapshot, evaluator, and syntax trees. Apply rechecks these dependencies and links the result to Change history.
Correct a held import.Push a corrected commit, or choose Retry verification to explicitly retest. Polling watches for new commits without repeatedly executing the same failed attempt. If both sides changed, review the conflict first. Turning the setting off allows pending imports without these saved-case checks and asks for confirmation.

No saved cases, failing cases, an execution error, an incomplete result, or a 30-second execution timeout prevents import. Suites are limited to 25 tested mappings and 100 cases; verification shares the workspace limit of one active run and 30 starts per hour. Capacity problems retry with backoff; configuration stays unchanged while waiting. If the branch moves during testing, ModernEDI checks it again before importing. A changed workspace or dependency cannot borrow an older pass.

This is a sample-based mapping check, not a pull-request approval system or a scenario runner. The incoming commit also supplies its expectations, so repository write access remains trusted: an author can change or remove tests. Generated-X12 validation runs only for cases that explicitly enable it. No documents are sent, and a pass does not prove runtime activation, delivery, or partner acceptance. Use conversation verification afterward when you want real traffic evidence for the newly applied configuration.

When both sides change

If the workspace and repository changed differently since their last successful synchronization, ModernEDI pauses without overwriting either copy. The workspace owner compares them and explicitly chooses the version to keep. This is conflict detection and resolution, not automatic merging of arbitrary source edits.

Open Change history → External repository → Review differences.Reading the comparison does not change the workspace or Git. It uses the current applied configuration, not unapplied editor drafts.
Choose which complete configuration to keep.Keep workspace version previews what will be added, changed, or removed in the repository. Keep repository version previews what will change in ModernEDI, including validation problems and affected conversations. Changing direction clears your acknowledgement.
Review named resources and removals first.Expand a resource to compare settings and map source. The detailed comparison highlights changed lines, offers a side-by-side view, and keeps complete before/after text available. Settings ignore JSON property order; source whitespace and array order still matter. Very large changes show an explicit fallback rather than an incomplete highlighted diff.
Acknowledge the impact, then confirm.ModernEDI binds the choice to the exact workspace snapshot and repository commit reviewed, checks them again before synchronization, and asks for another review if either changed. Applying the repository version also requires the same validated plan, including its runtime dependencies. A repository update is a normal commit, never a force-push. A workspace update uses the ordinary validated configuration apply and appears in Change history.

If the repository configuration directory is missing, the review only offers to restore it from the workspace. A missing directory is not interpreted as a request to delete your workspace. Stored secret values, transaction history, and prior verification evidence are not copied or erased; earlier scenario passes do not prove the newly applied configuration.

To combine edits from both sides, reconcile the configuration in your repository and prepare a new review. This first review experience does not select individual lines or resources to merge.

An invalid repository change is not partially applied. A change affecting active scenario runs may also be blocked. Fix the reported issue and synchronize again; do not weaken a check merely to clear the status.

Token expiry, rotation, and disconnection

If the token expires or is revoked, synchronization cannot complete, but existing workspace configuration remains. With the current controls, replace credentials by disconnecting and reconnecting the same repository, branch, and directory with the new token. Compare divergent copies before resolving them, then revoke the old token.

Disconnecting stops automatic synchronization. It does not require abandoning browser editing or removing live configuration. Keep credentials in your password manager or secret store, not in screenshots, issue descriptions, or Git.

Optional: keep sample checks with your maps

You can save and run mapping tests without connecting a repository. Follow Test and deploy a mapping safely for the browser workflow, exact comparison, and optional durable server verification.

Cases live in the mapping's spec.regressionCases array and enter configuration and connected Git history when applied. Editing only cases does not republish the live map or refresh scenario bindings. Remove customer data and secrets before saving: deleting a case later does not erase earlier Git history. Public Mapper share links omit saved cases.

Git stores the fixtures, not execution results. Optional server-owned results stay linked to configuration history and their exact tested identities. Enable saved-case checks before repository imports if you want automatic synchronization to require a current pass. A repository commit alone is not verification or proof of delivery.

See which conversations a change affects

For a current active revision, choose Review new run to open its existing scenario start form. ModernEDI checks the exact change first; you then review its Test or Production traffic and parameters before explicitly starting. Accepted Git edits, browser deployments, and reviewed recovery use the same path. Verify again after a change explains stale changes, retired bindings, and permissions.

After deployment, Change history → Conversations in this change links the operation to the exact binding revisions it created or retired, and to their latest retained runs. Each tenant-applied run links back to the change that created its binding. A new revision never inherits an earlier revision's pass. Read One change, from map to evidence for a concrete example.

If you use scenarios, mapping, partner, and AS2-connection reviews show the affected conversations and their latest completed run on the exact existing binding revision. A previous pass describes that earlier configuration, not your proposed change. Follow its evidence link to inspect the report; after a binding refresh, start another conversation verification when you want proof for the new configuration.

ModernEDI does not start runs or send documents automatically from a review. Missing or historical evidence is labeled, and mapping-only workspaces need no scenario setup. Saved tests check sample outputs and can opt into generated-X12 validation; conversation runs check real document and acknowledgment evidence.

The What needs verification? overview brings current binding revisions and their retained evidence together after browser edits, accepted Git changes, or recovery. Test and Production remain separate; earlier passes never transfer to a new revision. The optional generated-X12 check travels with each saved outgoing case, so browser review and API verification do not need separate test definitions.

Optional: observe changes from your own system

Your server or CI can use a ModernEDI Integration API key with configuration:read to confirm the workspace and calling key, read the existing external repository's synchronization status, retrieve its current import-test result, and page through configuration change history. These are the same server records used by the browser; no browser login or Git-provider token is needed for these reads.

Start with GET /v1/configuration/context to check the expected workspace and key IDs, then GET /v1/configuration/external-repository. Its optional import-verification reference leads to the saved-case evidence; a missing result is not a pass. GET /v1/configuration/apply-operations lists browser deployments, API changes, and accepted Git imports together. The API reference and official TypeScript, Python, and .NET SDKs describe these reads and their pagination.

Reading status does not trigger synchronization, run tests, or change configuration. A workspace owner still manages the connection and import-test setting in the browser. Reported commits describe the last successful synchronization, not a fresh check of the remote branch. All of this is optional: partner mappings remain sufficient to process documents.

Optional: run reviewed changes through your own CI

The configuration runner offers plan, optional verify, apply-reviewed, and wait for any CI system that can run Node.js. It rechecks the exact reviewed plan before applying; it is not required for browser authoring or automatic synchronization.

Explore the public configuration-example repository for a complete synthetic file layout and GitHub Actions. Adopt it in a private copy using your workspace's complete export, not by applying the sample over existing configuration. Live jobs are off by default. The hosted apply workflow requires private-repository branch and environment review protections supported by your GitHub plan; otherwise use reviewed local runner commands. See SDKs and configuration automation for the distinction.

verify runs the same saved mapping cases against the full desired configuration on the server, with up to 25 tested mappings and 100 cases. The report identifies the exact plan and lists how many mappings have no cases. You can explicitly require a current passing run during apply using --verification-run-id; the server validates its own stored result and links it to Change history. Omit that flag to deploy normally without a test gate. Verification checks mapping outputs, not AS2 delivery or scenario success. See the Integration API for the provider-neutral verification contract.

After an apply succeeds, your application can optionally start a scenario without copying browser state. Use that apply's operation ID and the binding ID from your source files to retrieve the exact runtime selection, then explicitly start a run and attach real transactions. ModernEDI rejects discovery if the workspace has changed since that apply. This is separate from saved mapping tests: a successful apply does not itself prove a conversation or send EDI.

Decide which workflow owns applying a branch. Do not assume a separate CI approval gate protects a branch that automatic synchronization is already authorized to apply. Introduce enforced approval policies only as an explicit part of your team's workflow.