Flows and Trails

This document outlines recommended naming conventions for Flows and Trails as they closely relate to each other in Kosli. Adopting these conventions will help maintain clarity and consistency across your organization.

Flows

A clear naming convention transforms a simple ID into a meaningful identifier that everyone understands. This shared language ensures attestations go to the right place and you can track your releases from start to finish. The naming convention relates to FLOW-NAME in Kosli CLI command:

kosli create flow FLOW-NAME [flags]

See CLI documentation for more details. The following sections define conventions for the two main types of Flows in Kosli: Build Flows and Release Flows.

Build Flows

Represent how code changes move from commit to artifact. Convention: org unit - repo-[service]

org unit

string

required

Your organizational unit, division or team name

repo

string

required

Your repository name

service

string

The specific service or component that the artifact belongs to

You can skip service if your repository produces only one artifact, i.e. non-monorepo setups.

examples on FLOW-NAME

snake_case
camelCase
PascalCase

investment-web_app (single artifact)
investment-web_app-frontend (with service: frontend)
devops_team-mobile_app-backend (with service: backend)

Regex:

^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*(-[a-z][a-z0-9_]*)?$

investment-webApp (single artifact)
investment-webApp-frontend (with service: frontend)
devopsTeam-mobileApp-backend (with service: backend)

Regex:

^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*(-[a-z][a-zA-Z0-9]*)?$

Investment-WebApp (single artifact)
Investment-WebApp-Frontend (with service: frontend)
DevOpsTeam-MobileApp-Backend (with service: backend)

Regex:

^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)?$

Release Flows

Represent how artifacts move from binary repository to deployment. Name Convention: org unit-repo

org unit

string

required

Your organizational unit, division or team name

repo

string

required

Your repository name

examples on FLOW-NAME

snake_case
camelCase
PascalCase

investment-web_app
devops_team-mobile_app

Regex:

^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*$

investment-webApp
devopsTeam-mobileApp

Regex:

^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*$

Investment-WebApp
DevOpsTeam-MobileApp

Regex:

^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*$

Trails

The naming convention for Trails depends on the type of Flow they are associated with: Build Flows or Release Flows and relates to TRAIL-NAME in Kosli CLI command:

kosli begin trail TRAIL-NAME \
  --flow FLOW-NAME \ # Build or Release Flow
  [other flags]

See CLI documentation for more details.

Associated with Build Flows

Name Convention: sha

sha

string

required

The Git commit HEAD SHA that triggered the build.

examples on TRAIL-NAME

Casing does not matter for SHA values, so we do not provide multiple casing options here.

abcdef1234567890abcdef1234567890abcdef12 (full 40-char SHA)
abcdef123 (short SHA)

Regex:

^[a-f0-9]+$

Associated with Release Flows

Convention: env - pr number

env

string

required

The target deployment environment (e.g., staging, production)

pr number

string

required

The pull request or change request number associated with the deployment.

examples on TRAIL-NAME

snake_case
camelCase
PascalCase

staging-42
production-108

Regex:

^[a-z][a-z0-9_]*-[0-9]+$

staging-42
production-108

Regex:

^[a-z][a-zA-Z0-9]*-[0-9]+$

Staging-42
Production-108

Regex:

^[A-Z][a-zA-Z0-9]*-[0-9]+$

Phase 1: Initial Discovery

Phase 2: Configure Kosli

Flows

Build Flows

Release Flows

Trails

Associated with Build Flows

Associated with Release Flows

Phase 1: Initial Discovery

Phase 2: Configure Kosli

Documentation Index

​Flows

​Build Flows

​Release Flows

​Trails

​Associated with Build Flows

​Associated with Release Flows

Flows

Build Flows

Release Flows

Trails

Associated with Build Flows

Associated with Release Flows