Skip to main content

Git Workflow for Development

This page covers how to organize branches once your team is working in Git — a stable main flow, with independent subflow branches merged back through pull requests. For the end-to-end path a change takes from your workspace to production, see The Development Lifecycle.

Key concepts​

Main flow — the primary development line. It should always be in a stable state and serve as the source of truth for everyone. Give it a branch that the whole team treats as the merge target, such as develop.

Subflows — independent workstreams for different parts of the main flow. Each subflow is developed in its own branch, for example:

  • feature/subflow-a
  • feature/subflow-b
  • feature/subflow-c

The reason this works is mechanical rather than procedural: each subflow is a separate artifact in the repository, so two developers working on two subflows are editing two different files, and their branches merge without touching each other.

The workflow​

Step 1: Start from an up-to-date main flow​

Check out your main flow branch and select Pull. A new branch inherits whatever you currently have checked out, so this step decides what your work is based on.

Step 2: Create a subflow branch​

For each sub-task or feature, create a separate branch from the main flow — one for Subflow A, one for Subflow B, and so on. Create it from the Branches tab so your organization's naming patterns are applied. See Git Branching Policy.

Step 3: Work on each subflow independently​

Within each subflow branch, add or update the workflows, schemas, and resources that subflow needs. Commit often with messages that describe what changed and why — Added approval logic to Subflow A, not just the file name.

Push regularly. Your changes live in your browser's LocalDataStore until you push, so unpushed work exists in exactly one place.

Step 4: Keep subflows in sync​

Bring the latest main flow changes into your subflow periodically. This keeps your branch from drifting, and fixing a small difference now is far easier than resolving a large conflict at the end of a release.

Sync at a natural pause — after a piece of work is complete, not mid-edit.

Step 5: Merge back into the main flow​

Merging happens in your Git provider, not in Koodisi. Push your subflow branch, raise a pull request against the main flow branch, and have your team review and merge it there. See Merging and Pull Requests.

Once merged, everyone benefits from the work and the main flow remains the single up-to-date version. Repeat for each subflow.

Step 6: Delete finished subflow branches​

After a subflow is merged, delete its branch in your Git provider, then select More > Fetch & Prune in Koodisi so the Remote list reflects the branches that still exist. This keeps it clear which work is still active.

Sequencing shared artifacts​

The model above assumes each branch owns its own artifacts. When several subflows depend on one shared schema or resource, that dependency is sequenced rather than developed in parallel:

  1. Create a branch containing only the shared change.
  2. Merge it into the main flow first.
  3. Have every dependent branch pull the main flow before mapping against the new shape.

Schemas need this discipline most, because workflow mappings depend on their shape and an edited schema becomes branch-scoped. See Schema Guidelines.

Practices that keep merges small​

  • Always branch from the main flow, not from another subflow.
  • Sync regularly with the main flow rather than at the end of a release.
  • Keep updates small and frequent so each is easy to understand and integrate.
  • One subflow per feature or task, so branches stay focused.
  • Validate before merging, so a broken change never reaches the main flow.
  • Delete branches after merging so only active work is visible.

Why this prevents conflicts​

Each person works on their own subflow, so branches rarely overlap. Frequent syncing prevents the large end-of-release merges that are hard to resolve. The main flow stays stable because it only ever receives reviewed work. And the history stays readable, so it is easy to see what changed and why.

For dividing work across several developers in more detail — including a worked three-developer example — see Parallel Development with Multiple Developers.