A code change travels from a developer laptop to production through a pipeline: build, test, package, deploy to staging, approve, then roll out carefully. This UML activity diagram shows that flow, with swimlanes that make it clear who or what does each step.
It is the diagram to reach for when a process has branches, parallel work and hand-offs.
1. The Diagram
The developer pushes a commit; the CI server checks it out, builds it and runs unit tests.
The decision diamond tests the result. [fail] sends the flow back to the developer to fix the code and push again; the loop is drawn explicitly.
[pass] reaches a fork bar: linting with static security analysis (SAST) and integration tests run in parallel. The join bar waits for both to finish.
CI builds a container image, tagged with the commit SHA, and pushes it to the registry. The same image is deployed to staging and smoke-tested.
A failed smoke test ends that branch at a flow final node (circle with X); the team is alerted and nothing reaches production.
On pass, a release owner approves. The image goes out as a 10% canary while error rate and latency are watched. Healthy: promote to 100%. Unhealthy: roll back to the previous image. Both end at an activity final node.
2. How to Read It
Arrows are control flow: a step starts when the arrow into it fires. Guards in square brackets on the arrows out of a diamond must not overlap, and together they should cover every case.
3. Variant: GitOps Loop
With GitOps the deploy step changes shape. CI only edits the image tag in a config repository. An agent such as Argo CD or Flux runs inside the cluster, notices the new commit and syncs the cluster to match. If health checks report degraded, the fix is a git revert, which loops back through the same sync. No lanes are drawn here: with one actor per step, lanes add little.
4. Pros and Cons
Pros
Shows branches, loops and parallel steps in one picture.
Swimlanes make hand-offs and ownership visible, which is where pipelines often stall.
Readable by non-developers: release managers and auditors follow it easily.
Maps well to pipeline configs (GitHub Actions jobs and needs, GitLab stages, Jenkins stages).
Good for spotting missing failure paths such as "what if staging fails?".
Cons
Large processes sprawl across pages; split by stage.
Does not show data or timing; a 40-minute test and a 2-second lint look the same.
Swimlanes force a layout that can create long crossing arrows.
Easy to drift from the real pipeline YAML unless generated or reviewed with it.
5. When to Use It
Use it when
Documenting or redesigning a build and release process.
Explaining who approves what in a regulated delivery flow.
Any workflow with decisions, retries and parallel work.
Skip it when
You need the internal states of one object: use a state machine.
You need exact message order between services: use a sequence diagram.
The pipeline is a straight line with no branches; a numbered list is clearer.
6. As Diagrams-as-Code
The main diagram written for PlantUML:
@startuml
|Developer|
start
repeat
:Push commit;
|CI server|
:Checkout and build;
:Run unit tests;
backward :Fix code;
repeat while (tests pass?) is ([fail]) not ([pass])
|CI server|
fork
:Lint + SAST;
fork again
:Integration tests;
end fork
:Build image;
|Registry / staging|
:Push to registry;
:Deploy to staging;
:Smoke tests;
if (smoke tests pass?) then ([fail])
kill
else ([pass])
endif
|Production|
:Approve release;
:Canary deploy 10%;
:Watch error rate;
if (healthy?) then ([healthy])
:Promote to 100%;
else ([unhealthy])
:Roll back;
endif
stop
@enduml
PlantUML activity syntax uses |Lane| to switch swimlanes, fork / end fork for parallel work and repeat ... repeat while with backward for the fix loop, and kill for a flow final.
7. Related
UML Activity Diagrams — notation reference for actions, decisions, forks and partitions