Flows and Trails

Recommended naming conventions for Flows and Trails in Kosli.

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

• 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_]*)?$

camelCase

• 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]*)?$

PascalCase

• 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

• investment-web_app
• devops_team-mobile_app

Regex:

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

camelCase

• investment-webApp
• devopsTeam-mobileApp

Regex:

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

PascalCase

• 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

• staging-42
• production-108

Regex:

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

camelCase

• staging-42
• production-108

Regex:

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

PascalCase

• Staging-42
• Production-108

Regex:

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