• Home
• Implementation guide
• Phase 2: Configure Kosli
• Plan Organizational Structure
• Naming Conventions
• Flows and Trails

Flows and Trails Naming Conventions #

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.
• Release Flows: Represent how artifacts move from binary repository to deployment.

Build Flows #

Name Convention: org unit-repo-[service]

• org unit: Your organizational unit, division or team name
• repo: Your repository name
• service (Optional): 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.

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

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

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

Release Flows #

Name Convention: org unit-repo

• org unit: Your organizational unit, division or team name
• repo: Your repository name

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

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

^[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.

Trails associated with Build Flows #

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

Name Convention: sha

• sha: The git commit HEAD SHA that triggered the build.

Examples on TRAIL-NAME:

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

Regex:

^[a-f0-9]+$

Trails associated with Release Flows #

Name Convention: env-pr number

• env: The target deployment environment (e.g., staging, production)
• pr number: The pull request or change request number associated with the deployment.

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

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

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