Team Collaboration Patterns

This guide describes different collaboration patterns for teams using Git Connectivity in Flowable Design. Choose the pattern that best fits your team size, workflow complexity, and release process.

Pattern 1: Trunk-Based Development

Best for: Small teams (2-3 modelers), simple apps, rapid iteration.

In trunk-based development, everyone works directly on the main branch:

1. All team members pull from and commit to main.
2. Commits are frequent and small.
3. Everyone pulls regularly to minimize divergence.
4. Conflicts are rare and resolved immediately.

Advantages:

• Simple workflow with minimal overhead.
• Changes are immediately available to all team members.
• No branch management required.

Considerations:

• Requires good team communication about who is editing which models.
• No review gate before changes land on main.
• Less suitable for teams that need formal review processes.

Pattern 2: Feature Branch Workflow

Best for: Medium teams (3-8 modelers), apps with formal review processes.

The feature branch workflow uses branches and pull requests to isolate and review changes:

1. Work starts on a feature branch (e.g., feature/new-claims-process).
2. The modeler commits changes to the feature branch.
3. When ready, a pull request is created from the feature branch to main.
4. Team members review the PR using the Git hosting platform's review tools.
5. After approval, the PR is merged into main.
6. Team members switch back to main and pull the merged changes.

Advantages:

• Changes are reviewed before merging, catching issues early.
• Modelers can work on features independently without affecting main.
• Clear audit trail of who approved what.

Considerations:

• Longer-lived branches increase the risk of merge conflicts.
• Requires team discipline around branch naming and PR descriptions.
• Review turnaround time can slow down progress.

tip

Keep feature branches short-lived. The longer a branch diverges from main, the more likely and complex conflicts become. Aim to merge within a few days.

Pattern 3: Environment Branches

Best for: Teams with multi-environment deployment pipelines (dev, staging, production).

Environment branches map to deployment targets:

1. Development work happens on develop (or feature branches merged into develop).
2. When ready for testing, changes are merged to staging via a pull request.
3. After testing, changes are promoted to main (or production) via another pull request.
4. CI/CD pipelines deploy models to the corresponding Flowable Work environment on each merge.

feature/xyz --> develop --> staging --> main (production)

Advantages:

• Clear separation between development, testing, and production states.
• Each environment always reflects a specific branch.
• Rollbacks are straightforward (revert the merge on the target branch).

Considerations:

• More complex branch management.
• Requires CI/CD integration for automated deployments.
• Cherry-picking hotfixes across branches can be complex.

Permission Model for Teams

Git Connectivity permissions can be assigned based on team roles:

Role	Permissions	Can Do
Admin	DESIGN_GIT_PROVIDER_MANAGEMENT + DESIGN_GIT_MANAGE + DESIGN_GIT_PUSH	Everything: manage providers, connect/disconnect repos, commit, pull, create PRs
Lead Modeler	DESIGN_GIT_MANAGE + DESIGN_GIT_PUSH	Connect apps to repos, manage branches, commit, pull, create PRs
Modeler	DESIGN_GIT_PUSH	Commit changes, pull remote changes, create PRs
Viewer	(no Git permissions)	View models but cannot interact with Git

info

These permissions are additive. A user needs DESIGN_GIT_PUSH for day-to-day operations, DESIGN_GIT_MANAGE for repository setup and branch management, and DESIGN_GIT_PROVIDER_MANAGEMENT only for initial provider configuration.

Working with CI/CD

Git-connected apps enable CI/CD integration through standard Git hooks and pipelines:

Automated Deployment on Merge

Configure your CI/CD pipeline (GitHub Actions, GitLab CI, Bitbucket Pipelines, etc.) to:

1. Trigger on pushes to specific branches (e.g., main, staging).
2. Export the Flowable models from the repository.
3. Deploy them to the corresponding Flowable Work environment using the deployment API.

PR Validation

Configure PR checks to:

1. Validate model JSON structure.
2. Run automated tests against the models.
3. Check for naming convention compliance.

This adds an automated quality gate on top of manual PR reviews.

Best Practices

• Agree on a workflow before starting. Choose a collaboration pattern and communicate it to the team. Consistency is more important than choosing the "best" pattern.
• Use descriptive branch names. Prefix with the purpose: feature/, fix/, refactor/. Include a ticket number if applicable.
• Write meaningful commit messages. Explain the intent, not just the change. Your future self and teammates will thank you.
• Pull before you push. Always pull the latest changes before committing to minimize conflicts.
• Keep branches short-lived. Merge feature branches within days, not weeks.
• Review model changes like code. Pull requests for model changes benefit from the same review rigor as code changes.