Getting StartedUpdated July 3, 2026

GitHub Workflow Guide

guidegithubworkflowgit-flowpull-requestscode-reviewci-cdbranchingcollaboration

GitHub Workflow Guide

Master Collaborative Development on Epic on Azure Platform

</div>

What You'll Master: Branch strategies, pull requests, code reviews, and deployment workflows

Additional Resources:

Security Development Guidelines - Security best practices
Best Practices & Standards - Development guidelines and standards

Master the Epic on Azure Development Process

<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 2rem; border-radius: 8px; margin: 1rem 0;" markdown="1"> <h2 style="color: white; margin-top: 0;">🚀 GitHub Flow for Healthcare Excellence</h2> <p style="font-size: 1.1em; margin-bottom: 0;">Our streamlined workflow ensures <strong>secure, collaborative development</strong> of Epic healthcare solutions. Every pull request contributes to better patient care through reliable software delivery.</p> </div>

GitHub Flow Overview

GitHub Flow is our lightweight, branch-based workflow that prioritizes continuous integration and collaborative development. Every change goes through pull requests to ensure code quality, security compliance, and team alignment.

gitgraph
    commit id: "Initial Setup"
    branch feature/epic-integration
    checkout feature/epic-integration
    commit id: "Add Epic APIs"
    commit id: "Add tests"
    commit id: "Update docs"
    checkout main
    merge feature/epic-integration
    commit id: "Deploy v1.2.0"
    branch feature/patient-portal
    checkout feature/patient-portal
    commit id: "Portal UI"
    commit id: "Security review"

Core Principles:

🏠 Main branch is always deployable - Production-ready at all times
🌿 Feature branches for all changes - Isolated development environments
📝 Pull requests for collaboration - Peer review and discussion
⚡ Deploy frequently - Small, incremental improvements

</div>

Complete Workflow Guide

📥 Step 1: Clone the Repository

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 2rem; margin: 2rem 0;" markdown="1"> <div style="background: #e8f5e8; border-left: 4px solid #4caf50; padding: 1.5rem; border-radius: 4px;" markdown="1"> <h4 style="margin-top: 0; color: #2e7d32;">🖥️ Command Line</h4>

# Clone the repository
git clone https://github.com/optum-tech-compute/your-repo.git

# Navigate to the project
cd your-repo

# Verify remote connection
git remote -v

<p><strong>Why this matters:</strong> Creates your local development environment with full Git history and remote tracking.</p> </div> <div style="background: #e3f2fd; border-left: 4px solid #2196f3; padding: 1.5rem; border-radius: 4px;" markdown="1"> <h4 style="margin-top: 0; color: #1565c0;">🎨 VS Code Method</h4>

Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Search: Git: Clone
Enter Repository URL
Select Local Folder
Open Cloned Repository

<p><strong>Why this matters:</strong> VS Code automatically configures Git integration and workspace settings for optimal development experience.</p> </div> </div>

🌿 Step 2: Create a Feature Branch

Branch Naming Convention:

feature/description - New functionality
bugfix/issue-number - Bug fixes
hotfix/critical-issue - Emergency fixes
docs/update-topic - Documentation updates

</div> <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 2rem; margin: 2rem 0;" markdown="1"> <div style="background: #f0f8ff; border-left: 4px solid #007acc; padding: 1.5rem; border-radius: 4px;" markdown="1"> <h4 style="margin-top: 0; color: #003d66;">💻 Git CLI Commands</h4>

# Ensure you're on main branch
git checkout main

# Pull latest changes
git pull origin main

# Create and switch to new branch
git checkout -b feature/epic-patient-portal

# Verify branch creation
git branch

</div> <div style="background: #f8f0ff; border-left: 4px solid #6f42c1; padding: 1.5rem; border-radius: 4px;" markdown="1"> <h4 style="margin-top: 0; color: #3d1a78;">🎨 VS Code Branch Management</h4>

Click branch name in status bar (bottom-left)
Select: "Create new branch..."
Enter branch name: feature/epic-patient-portal
Branch icon appears in status bar
Source Control panel shows active branch

</div> </div>

🎯 Impact: Isolates your work from main branch, enabling parallel development and safe experimentation.

✏️ Step 3: Make Your Changes

Best Practices for Epic on Azure Development:

🏥 Patient Data Security - Never commit PHI or sensitive health information
🔒 Secrets Management - Use HashiVault for all credentials and API keys
🧪 Test Early - Run tests locally before committing
📚 Document Changes - Update relevant documentation and comments
🔍 Code Quality - Follow our coding standards and linting rules

</div>

Development Guidelines:

// ✅ Good: Secure configuration
const dbConfig = {
  host: process.env.DB_HOST,
  password: await vault.get('epic/database/password'),
  encryption: 'AES-256'
};

// ❌ Bad: Hardcoded secrets
const dbConfig = {
  host: 'epic-db.internal.com',
  password: 'SuperSecret123!',
  encryption: false
};

📦 Step 4: Stage Your Changes

# View changed files
git status

# Stage specific files
git add src/components/PatientPortal.js
git add docs/patient-portal.md

# Stage all changes (use carefully)
git add .

# Review staged changes
git diff --cached

</div> <div style="background: #e3f2fd; border-left: 4px solid #2196f3; padding: 1.5rem; border-radius: 4px;" markdown="1"> <h4 style="margin-top: 0; color: #1565c0;">🎨 VS Code Staging</h4>

Open Source Control (Ctrl+Shift+G)
Review "Changes" section
Click + next to files to stage individually
Or click "Stage All Changes" for bulk staging
Preview changes in diff viewer

<p><strong>Pro Tip:</strong> Use "Discard Changes" to reset unwanted modifications.</p> </div> </div>

🎯 Purpose: Staging allows you to group related changes into logical commits, making your Git history clear and meaningful.

💾 Step 5: Commit Your Changes

Conventional Commits Standard:

We follow Conventional Commits for consistent, meaningful commit messages:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Allowed commit types (org ruleset — non-canonical prefixes are rejected):

feat — new features or enhancements
fix — bug fixes and corrections
docs — documentation changes
style — formatting/whitespace, no behavior change
refactor — code improvements without functional changes
perf — performance improvements
test — adding or updating tests
build — build system or dependency changes
ci — CI/CD pipeline changes
chore — maintenance, including security rotations and dependency bumps
revert — reverting a prior commit

For security-flavored work use chore(security) or fix(security) — there is no security: type.

# Good commit examples
git commit -m "feat(portal): add patient authentication flow"
git commit -m "fix(api): resolve Epic integration timeout"
git commit -m "docs(readme): update installation steps"
git commit -m "chore(security): implement MFA for admin users"

# Multi-line commit with body
git commit -m "feat(portal): add patient data dashboard

- Display patient vitals and medication history
- Implement real-time updates from Epic
- Add accessibility features for screen readers
- Include data export functionality

Closes #123"

Write commit message in text box
Use conventional format: type(scope): description
Click checkmark to commit
Or use Ctrl+Enter keyboard shortcut

VS Code Tips:

Install "Conventional Commits" extension for auto-suggestions
Use "Git Graph" extension to visualize commit history
Enable git.enableCommitSigning if your team requires signed commits

</div> </div>

🚀 Step 6: Push Your Branch

# First push (sets upstream tracking)
git push -u origin feature/epic-patient-portal

# Subsequent pushes (after upstream is set)
git push

# Force push: only after a deliberate rebase, never to a shared branch
# without coordination. Prefer --force-with-lease over --force so you
# do not silently overwrite a teammate's pushed commits.
git push --force-with-lease

What happens:

📤 Uploads your branch to GitHub
🔗 Sets upstream tracking (with -u flag)
👥 Makes your work visible to team members
🔄 Enables collaboration and code review

VS Code: Click "Publish Branch" or use "Sync Changes" button in Source Control panel.

</div>

📋 Step 7: Create a Pull Request

Pull Request Best Practices:

🎯 Title Format: Use conventional commit style

feat(portal): Add patient authentication and dashboard

📝 Description Template:

## Changes Made
- Implemented patient login with Epic SSO
- Added dashboard with real-time vitals
- Integrated with Epic FHIR APIs

## Testing
- [ ] Unit tests pass (95% coverage)
- [ ] Integration tests with Epic sandbox
- [ ] Security scan completed
- [ ] Accessibility testing (WCAG 2.1 AA)

## Security Considerations
- Patient data encrypted in transit and at rest
- RBAC implemented for different user roles
- Audit logging enabled for all data access

## Deployment Notes
- Requires new environment variables (see .env.example)
- Database migration included (see migration.sql)
- Epic endpoint configuration needed

## Screenshots
![Patient Dashboard](https://user-images.githubusercontent.com/...)

Closes #123

</div> <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1rem; margin: 2rem 0;" markdown="1"> <div style="background: #e3f2fd; padding: 1rem; border-radius: 8px; border-left: 4px solid #2196f3;" markdown="1"> <h4 style="margin-top: 0; color: #1565c0;">🌐 GitHub Web Interface</h4> <ol style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li>Navigate to repository on GitHub</li> <li>Click "Compare & Pull Request" button</li> <li>Fill in title and description</li> <li>Assign reviewers and labels</li> <li>Link related issues</li> <li>Click "Create Pull Request"</li> </ol> </div> <div style="background: #f3e5f5; padding: 1rem; border-radius: 8px; border-left: 4px solid #9c27b0;" markdown="1"> <h4 style="margin-top: 0; color: #7b1fa2;">🖥️ GitHub CLI Method</h4> <pre style="margin: 0; font-size: 0.8rem;"><code># Create PR from command line gh pr create --title "feat(portal): Add patient dashboard" \ --body "Implements new patient portal with Epic integration" \ --reviewer @teammate1,@teammate2 \ --label enhancement,security-review

View PR status

gh pr status

Open PR in browser

gh pr view --web</code></pre>

</div> <div style="background: #fff3e0; padding: 1rem; border-radius: 8px; border-left: 4px solid #ff9800;" markdown="1"> <h4 style="margin-top: 0; color: #f57c00;">🎨 VS Code GitHub Extension</h4> <ol style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li>Install "GitHub Pull Requests" extension</li> <li>Click "Create Pull Request" in Source Control</li> <li>Fill in PR details in VS Code</li> <li>Review changes in diff view</li> <li>Submit directly from editor</li> </ol> </div> </div>

🔍 Step 8: Code Review Process

Our Review Standards:

<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); gap: 1rem; margin: 1rem 0;" markdown="1"> <div style="background: #e8f5e8; padding: 1rem; border-radius: 6px;" markdown="1"> <h5 style="margin: 0 0 0.5rem 0; color: #2e7d32;">✅ Required Checks</h5> <ul style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li>All CI/CD tests pass</li> <li>Security scan clean</li> <li>Code coverage >80%</li> <li>No critical linting errors</li> </ul> </div> <div style="background: #e3f2fd; padding: 1rem; border-radius: 6px;" markdown="1"> <h5 style="margin: 0 0 0.5rem 0; color: #1565c0;">👥 Peer Review</h5> <ul style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li>At least one approval (per-repo branch protection — verify via <code>gh api</code>)</li> <li>Code readability</li> <li>Architecture alignment</li> <li>Performance considerations</li> </ul> </div> <div style="background: #fff3e0; padding: 1rem; border-radius: 6px;" markdown="1"> <h5 style="margin: 0 0 0.5rem 0; color: #f57c00;">🛡️ Security Review</h5> <ul style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li>No hardcoded secrets</li> <li>Proper authentication</li> <li>Data encryption compliance</li> <li>HIPAA requirements met</li> </ul> </div> </div>

Addressing Feedback:

# Make changes based on review comments
# Stage and commit improvements
git add .
git commit -m "fix(portal): address security review feedback"

# Push updates (automatically updates PR)
git push

</div>

✅ Step 9: Merge the Pull Request

Merge Strategies:

The set of allowed strategies is configured per repository. Check the target repo's "Pull Requests" settings (or run gh api repos/<owner>/<repo> and inspect allow_squash_merge, allow_merge_commit, allow_rebase_merge) before assuming any of these are available.

🔄 Squash and Merge (default for most ohemr-* repos)

Combines all commits into a single commit
Creates a clean, linear git history
Preserves PR discussion context

🌿 Merge Commit

Preserves individual commit history
Shows branching structure
Use for complex feature development — only where the repo permits it

⚡ Rebase and Merge

Linear history without merge commits
Individual commits preserved
Use for simple, clean commits — only where the repo permits it

Post-Merge Cleanup:

# Switch to main branch
git checkout main

# Pull latest changes (includes your merged PR)
git pull origin main

# Delete local feature branch
git branch -d feature/epic-patient-portal

# Delete remote branch (if not auto-deleted)
git push origin --delete feature/epic-patient-portal

</div>

🔄 Step 10: Stay Synchronized

Daily Sync Routine:

# Morning routine - sync with latest changes
git checkout main
git pull origin main

# Before starting new feature
git checkout -b feature/new-epic-feature

# During development - stay updated
git checkout main
git pull origin main
git checkout feature/new-epic-feature
git merge main  # or git rebase main

VS Code Sync:

Click "Sync Changes" button regularly
Enable auto-fetch in Git settings
Use "Pull" from Source Control menu

Why this matters: Prevents merge conflicts and ensures you're working with the latest codebase.

</div>

Workflow Optimization Tips

<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(300px, 1fr)); gap: 1rem; margin: 2rem 0;" markdown="1"> <div style="background: #e8f5e8; padding: 1rem; border-radius: 8px; border-left: 4px solid #4caf50;" markdown="1"> <h4 style="margin-top: 0; color: #2e7d32;">🚀 Speed Up Development</h4> <ul style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li><strong>Git Aliases:</strong> Create shortcuts for common commands</li> <li><strong>Pre-commit Hooks:</strong> Automatic code formatting and linting</li> <li><strong>Branch Templates:</strong> Standardized branch names</li> <li><strong>Saved Searches:</strong> Quick access to relevant PRs</li> </ul> </div> <div style="background: #e3f2fd; padding: 1rem; border-radius: 8px; border-left: 4px solid #2196f3;" markdown="1"> <h4 style="margin-top: 0; color: #1565c0;">🤝 Improve Collaboration</h4> <ul style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li><strong>Draft PRs:</strong> Share work-in-progress for early feedback</li> <li><strong>PR Templates:</strong> Consistent information in all requests</li> <li><strong>Code Owners:</strong> Automatic reviewer assignment</li> <li><strong>Status Checks:</strong> Enforce quality gates</li> </ul> </div> <div style="background: #fff3e0; padding: 1rem; border-radius: 8px; border-left: 4px solid #ff9800;" markdown="1"> <h4 style="margin-top: 0; color: #f57c00;">📊 Monitor Quality</h4> <ul style="margin: 0; padding-left: 1rem; font-size: 0.9rem;"> <li><strong>Branch Protection:</strong> Prevent direct pushes to main</li> <li><strong>Required Reviews:</strong> Ensure peer oversight</li> <li><strong>CI/CD Integration:</strong> Automated testing and deployment</li> <li><strong>Security Scanning:</strong> Detect vulnerabilities early</li> </ul> </div> </div>

Git Configuration for Epic on Azure

# Set your identity
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Useful aliases
git config --global alias.st status
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.cm "commit -m"
git config --global alias.log1 "log --oneline --graph --all"

# Security settings
git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.autocrlf input  # Unix/Mac
# git config --global core.autocrlf true  # Windows

🏆 Success Metrics & Team Standards

Individual Excellence Indicators

Code Quality Standards:

✅ PR approval rate >95%
✅ Code review turnaround <24 hours
✅ Zero critical security findings
✅ Conventional commit compliance >90%

Collaboration Metrics:

🤝 Active participation in code reviews
📝 Clear, helpful PR descriptions
🔄 Timely response to feedback
🎓 Knowledge sharing through comments

Team Performance Targets

Development Velocity:

🚀 Average PR merge time <48 hours
📊 95% of PRs pass CI on first try
🔄 <2 hour build and test pipeline
📈 80% code coverage on new features

Quality Assurance:

🛡️ Zero production incidents from code changes
🔒 100% security review compliance
📋 90% stakeholder satisfaction with deliveries
🎯 <5% post-deployment bug rate

</div>

📞 Getting Help & Resources

Support Channels

Git & GitHub Questions:

💬 Teams Channel: #epic-azure-github
🐙 GitHub Discussions: Epic on Azure Q&A
📚 Documentation: Support & FAQ

Code Review Support:

👥 Reviewer Pool: Available in #code-review-help
🎓 Mentorship: Paired reviewer program for new developers
📖 Best Practices: Best Practices & Standards

Emergency Assistance:

🚨 Critical Issues: Contact on-call engineer
🔐 Security Concerns: Immediately ping @security-team
🏥 Production Issues: Follow incident response procedure

</div>

Learning Resources

Git Mastery:

Epic on Azure Specific:

Security Development Guidelines - Security best practices and compliance
Best Practices & Standards - Development guidelines and standards

🎉 Ready to Contribute

<div style="background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 2rem; border-radius: 8px; margin: 2rem 0; text-align: center;" markdown="1"> <h2 style="color: white; margin-top: 0;">🚀 You're Ready to Build Amazing Healthcare Technology!</h2> <p style="font-size: 1.1em;">With this GitHub workflow, you're equipped to contribute to our Epic on Azure platform that serves <strong>millions of patients</strong> worldwide. Every commit you make has the potential to improve healthcare delivery.</p> <p style="margin-bottom: 0;"><strong>Remember:</strong> Code quality isn't just about functionality—it's about patient safety, data security, and reliable healthcare systems.</p> </div>

Next Steps:

🛠️ Practice: Create a test branch and practice the workflow
📋 First Contribution: Look for "good first issue" labels
🤝 Team Integration: Join our code review rotation
🎯 Continuous Learning: Attend our weekly Git & GitHub office hours

This workflow guide is actively maintained by the Epic on Azure Platform Team. Have suggestions for improvement? Create an issue or submit a pull request!

Last updated: August 2025 | Impact: Enabling secure, collaborative healthcare software development