Skip to content
Docs
Contact Us

Version Control Workflow

Version Control Workflow with MirthSync

Section titled “Version Control Workflow with MirthSync”

Learn how to effectively manage your Mirth Connect or Open Integration Engine configurations using Git and MirthSync. This guide covers proven workflows, branching strategies, and team collaboration patterns used by successful healthcare IT teams.

Workflow Overview

Section titled “Workflow Overview”
Mirth Connect to local files to Git remote workflow

Why Version Control for Healthcare Integration?

Section titled “Why Version Control for Healthcare Integration?”

Healthcare integration platforms like Mirth Connect and OIE manage critical data flows between systems. Without proper version control, teams face:

  • No audit trail - Can’t see who changed what channel configuration or when
  • Difficult rollbacks - Rolling back a problematic deployment requires manual intervention
  • Merge conflicts - Multiple developers can’t work simultaneously without stepping on each other
  • No code review - Changes go directly to production without peer review
  • Compliance risks - Regulatory requirements often mandate change tracking

MirthSync transforms your integration platform into versioned, reviewable, and auditable infrastructure as code.

Core Workflow Patterns

Section titled “Core Workflow Patterns”

Solo Developer Workflow

Section titled “Solo Developer Workflow”

Perfect for individual developers or small teams where one person manages Mirth Connect at a time.

Daily Workflow

Section titled “Daily Workflow”
Terminal window
# Set password once per session
export MIRTHSYNC_PASSWORD=your_password


# 1. Start your day - pull latest from Mirth Connect
./mirthsync.sh -s https://mirth.example.com:8443/api -u admin -t ./mirth-config pull


# 2. Review what's changed (if anything)
./mirthsync.sh -t ./mirth-config git status
./mirthsync.sh -t ./mirth-config git diff


# 3. Commit any changes from Mirth Connect
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Update ADT channel with new transformer logic" git commit


# 4. Push to remote backup
./mirthsync.sh -t ./mirth-config git push

Making Changes

Section titled “Making Changes”
Terminal window
# 1. Make changes in Mirth Connect Administrator Console
# (Add new channel, modify transformers, update code templates)


# 2. Pull changes to your local files
./mirthsync.sh -s https://mirth.example.com:8443/api -u admin -t ./mirth-config pull


# 3. Review the changes
./mirthsync.sh -t ./mirth-config git diff


# 4. Commit with descriptive message
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Add FHIR R4 patient admission channel


- Receives ADT^A01 messages on port 6661
- Transforms HL7 v2 to FHIR R4 Patient resource
- Posts to FHIR server at fhir.example.com
- Includes error handling for malformed messages" git commit


# 5. Push to remote
./mirthsync.sh -t ./mirth-config git push

Viewing History

Section titled “Viewing History”
Terminal window
# See commit history
./mirthsync.sh -t ./mirth-config git log


# See who changed what in a file (use native git)
cd ./mirth-config && git blame channels/ADT_Inbound/channel.xml && cd ..


# See changes over time (use native git for -p flag)
cd ./mirth-config && git log -p channels/ADT_Inbound/ && cd ..

Branching Strategies

Section titled “Branching Strategies”

Branch Naming Conventions

Section titled “Branch Naming Conventions”

Use consistent, descriptive branch names:

TypePatternExample
Featurefeature/<description>feature/adt-admission-channel
Bugfixbugfix/<issue> or fix/<issue>bugfix/hl7-parsing-error
Hotfixhotfix/<critical-issue>hotfix/production-channel-down
Releaserelease/<version>release/2.1.0
Experimentexperiment/<name>experiment/fhir-r5-support

Branch Lifecycle

Section titled “Branch Lifecycle”
Terminal window
# Create branch (use native git)
cd ./mirth-config && git checkout -b feature/new-integration && cd ..


# Work on branch (commit often)
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Progress on new integration" git commit


# Keep branch updated with main (use native git for rebase/merge)
./mirthsync.sh -t ./mirth-config git checkout main
./mirthsync.sh -t ./mirth-config git pull
./mirthsync.sh -t ./mirth-config git checkout feature/new-integration
cd ./mirth-config && git rebase main && cd ..  # or: git merge main


# When complete, create PR
gh pr create


# After merge, delete branch (use native git)
./mirthsync.sh -t ./mirth-config git checkout main
./mirthsync.sh -t ./mirth-config git pull
cd ./mirth-config && git branch -d feature/new-integration && cd ..
cd ./mirth-config && git push origin --delete feature/new-integration && cd ..

Commit Message Best Practices

Section titled “Commit Message Best Practices”

Good Commit Messages

Section titled “Good Commit Messages”
Terminal window
# Good - Clear, imperative, explains why
./mirthsync.sh -t ./mirth-config --commit-message "Add patient demographics validator to ADT channel


The validator checks for required fields (MRN, name, DOB) before
processing. This prevents downstream errors when required data is missing.


Refs: JIRA-123" git commit


# Good - Concise for simple changes
./mirthsync.sh -t ./mirth-config --commit-message "Update FHIR server URL to production endpoint" git commit


# Good - Explains context
./mirthsync.sh -t ./mirth-config --commit-message "Increase HTTP timeout for FHIR destinations


External FHIR server sometimes takes >30s to respond during peak hours.
Increased timeout to 60s to prevent false failures." git commit

Bad Commit Messages

Section titled “Bad Commit Messages”
Terminal window
# Bad - Not descriptive
./mirthsync.sh -t ./mirth-config --commit-message "Fixed stuff" git commit
./mirthsync.sh -t ./mirth-config --commit-message "Update" git commit
./mirthsync.sh -t ./mirth-config --commit-message "WIP" git commit


# Bad - Too vague
./mirthsync.sh -t ./mirth-config --commit-message "Made changes to ADT channel" git commit

Commit Message Template

Section titled “Commit Message Template”
<type>: <short summary> (50 chars or less)


<detailed description of what and why>
<wrap at 72 characters>


<optional footer with issue references>

Types: feat, fix, docs, style, refactor, test, chore

Pull Request Workflow

Section titled “Pull Request Workflow”

Creating Effective PRs

Section titled “Creating Effective PRs”
## Summary


Brief description of what this PR does and why.


## Changes


- Added HL7 v2.7 support to ADT channels
- Updated transformers for new patient identifier format
- Added validation for required demographics fields


## Testing


- Tested with sample HL7 messages
- Verified FHIR output format
- Checked error handling
- Deployed to dev environment successfully


## Deployment Notes


- Requires updating ADT_PORT environment variable
- New channel will be disabled by default, enable after deployment
- Backup current production config before deploying


## Related Issues


Closes #42
Refs #38, #40

Code Review Checklist

Section titled “Code Review Checklist”

Reviewers should check:

Functionality

  • Does the channel do what it claims?
  • Are edge cases handled?
  • Is error handling adequate?

Code Quality

  • Is transformer JavaScript clean and readable?
  • Are there code comments for complex logic?
  • Is there code duplication that could be extracted?

Testing

  • Has this been tested with real/sample data?
  • Are error conditions tested?
  • Does it work in all target environments?

Documentation

  • Are channel descriptions clear?
  • Is transformer logic documented?
  • Are deployment steps noted?

Security

  • Are credentials properly handled?
  • Is sensitive data logged?
  • Are connections encrypted?

Deployment Workflows

Section titled “Deployment Workflows”

Safe Deployment Process

Section titled “Safe Deployment Process”
Terminal window
# 1. Ensure you're on the right branch
./mirthsync.sh -t ./mirth-config git branch


# 2. Pull latest changes
./mirthsync.sh -t ./mirth-config git pull


# 3. Review what will be deployed
./mirthsync.sh -t ./mirth-config git log


# 4. Deploy to staging
./mirthsync.sh -s https://mirth-staging.example.com:8443/api -u admin -t ./mirth-config --deploy-all push


# 5. Test in staging
# Run smoke tests, verify channels...


# 6. If successful, deploy to production
./mirthsync.sh -s https://mirth-prod.example.com:8443/api -u admin -t ./mirth-config --deploy-all push


# 7. Verify production
# Check channels are running in Mirth Admin Console, test message flow


# 8. Tag the release (use native git)
cd ./mirth-config && git tag -a v2.1.0 -m "Production release 2.1.0" && cd ..
cd ./mirth-config && git push origin v2.1.0 && cd ..

Rollback Procedure

Section titled “Rollback Procedure”

If deployment goes wrong:

Terminal window
# Option 1: Revert to previous git commit
./mirthsync.sh -t ./mirth-config git log  # Find previous good commit
./mirthsync.sh -t ./mirth-config git checkout abc123  # Commit hash of last good version
./mirthsync.sh -s https://mirth-prod.example.com:8443/api -u admin -t ./mirth-config -f --deploy-all push


# Option 2: Use git revert (use native git - preserves history)
cd ./mirth-config && git revert HEAD && cd ..
./mirthsync.sh -s https://mirth-prod.example.com:8443/api -u admin -t ./mirth-config --deploy-all push

Team Collaboration Tips

Section titled “Team Collaboration Tips”

Communication Practices

Section titled “Communication Practices”

  1. Before modifying a channel

    Terminal window
    # Check commit history
    ./mirthsync.sh -t ./mirth-config git log
    

    # Use native git for blame
    cd ./mirth-config && git blame channels/ADT_Inbound/channel.xml && cd ..
    

    # Communicate with that person before making changes

  2. Use draft PRs for work-in-progress

    Terminal window
    gh pr create --draft --title "WIP: Lab integration"

  3. Tag team members for review

    Terminal window
    gh pr create --reviewer @teammate1,@teammate2

Conflict Prevention

Section titled “Conflict Prevention”
  • Assign ownership - Specific team members own specific channels
  • Communicate early - Mention in Slack/Teams when working on shared channels
  • Pull often - Run pull multiple times per day
  • Small commits - Commit frequently to reduce merge conflict size
  • Code templates - Extract common logic to code templates to reduce duplication

Advanced Workflows

Section titled “Advanced Workflows”

Cherry-Picking Changes

Section titled “Cherry-Picking Changes”

Apply specific commits to other branches:

Terminal window
# You fixed a bug in feature branch, need it in main (use native git)
./mirthsync.sh -t ./mirth-config git checkout main
cd ./mirth-config && git cherry-pick abc123 && cd ..  # Commit hash from feature branch
./mirthsync.sh -t ./mirth-config git push

Interactive Rebase

Section titled “Interactive Rebase”

Clean up commit history before merging:

Terminal window
# Squash last 3 commits into one (use native git)
cd ./mirth-config && git rebase -i HEAD~3 && cd ..


# In editor, change "pick" to "squash" for commits to combine
# Save and edit the combined commit message

Submodules for Shared Code

Section titled “Submodules for Shared Code”

If you manage multiple Mirth Connect instances:

Terminal window
# Create shared code templates repository (use native git)
cd ./mirthsync-shared-templates && git init && cd ..


# Add as submodule to each project (use native git)
cd ./mirth-config && git submodule add https://github.com/org/mirthsync-shared-templates shared && cd ..


# Update submodule in projects (use native git)
cd ./mirth-config && git submodule update --remote && cd ..

Troubleshooting Common Issues

Section titled “Troubleshooting Common Issues”

”I committed credentials!"

Section titled “”I committed credentials!"”
Terminal window
# Remove from history (before pushing!) - use native git
cd ./mirth-config
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch secrets.env" \
  --prune-empty --tag-name-filter cat -- --all
cd ..


# Add sensitive files to .gitignore
echo "*.env" >> ./mirth-config/.gitignore
echo "secrets.*" >> ./mirth-config/.gitignore
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Add secrets to gitignore" git commit


# Rotate the exposed credentials immediately!

"Git says my XML is binary"

Section titled “"Git says my XML is binary"”
Terminal window
# Add to .gitattributes
echo "*.xml text diff=xml" >> ./mirth-config/.gitattributes
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Configure XML files as text" git commit

"Too many merge conflicts”

Section titled “"Too many merge conflicts””

Consider restructuring:

  • Break monolithic channels into smaller ones
  • Extract common logic to code templates
  • Use channel groups to organize better
  • Coordinate timing of changes to shared channels

Tools & Integration

Section titled “Tools & Integration”

Git Hooks for Automation

Section titled “Git Hooks for Automation”

Pre-commit hook - Run checks before commit:

.git/hooks/pre-commit
#!/bin/sh
# Check for common issues in channel files
# Example: ensure no hardcoded passwords
if grep -r "password.*=.*['\"]" channels/ code-templates/; then
  echo "Possible hardcoded password found. Commit aborted."
  exit 1
fi


# Run JavaScript linting on transformers
npm run lint --if-present

Pre-push hook - Run tests before push:

.git/hooks/pre-push
#!/bin/sh
# Run channel tests
npm test


if [ $? -ne 0 ]; then
  echo "Tests failed. Push aborted."
  exit 1
fi

GitHub/GitLab Integration

Section titled “GitHub/GitLab Integration”
  • Branch protection - Require PR reviews before merge
  • Status checks - Require CI tests to pass
  • CODEOWNERS - Auto-assign reviewers based on files changed
  • Issue linking - Auto-close issues when PRs merge