Skip to main content

Stack Naming

carlin automatically generates CloudFormation stack names based on your project configuration, branch name, or environment. Understanding stack naming is critical because it determines how deployments are tracked and updated.

Automatic Stack Naming​

When you don't specify --stack-name, carlin generates the name using this algorithm:

  1. First part: Package name from package.json (or Stack-<random> if not defined)
  2. Second part: First defined value from:
    • --environment option
    • Git branch name (converted to param-case)
    • undefined (if neither is available)

Examples​

Package NameEnvironmentBranchStack Name
my-appProductionmainmy-app-Production
my-app-feature/authmy-app-feature-auth
@company/apiStaging-api-Staging
my-app-mainmy-app-main
(no package.json)Production-Stack-96830-Production
tip

Scoped package names (e.g., @company/api) use only the package name without the scope (api).

Custom Stack Names​

Override automatic naming with --stack-name:

carlin deploy --stack-name CustomStack

This creates or updates a stack named exactly CustomStack, regardless of package name, branch, or environment.

When to Use Custom Names​

  • Shared infrastructure: Base stacks used across multiple projects
  • Legacy stacks: Migrating from existing CloudFormation stacks
  • Fixed naming requirements: Compliance or organizational policies
  • Cross-project resources: VPCs, DNS zones, shared databases

Branch-Based Deployments​

carlin uses Git branch names to enable feature branch deployments:

# On branch: feature/user-authentication
carlin deploy
# Creates: my-app-feature-user-authentication

# On branch: fix/bug-123
carlin deploy
# Creates: my-app-fix-bug-123

# On branch: main
carlin deploy
# Creates: my-app-main

Branch names are automatically converted to param-case (lowercase with hyphens). Non-ASCII characters (e.g. accented letters like ç, ã) are normalized to their closest ASCII equivalents before the stack name is used.

Override Branch Detection​

Specify a different branch for stack naming:

carlin deploy --branch custom-branch

Or use environment variable:

CARLIN_BRANCH=custom-branch carlin deploy

Use case: Delete a deployment for a deleted branch:

# Branch feature/auth was already deleted but stack still exists
carlin deploy --destroy --branch feature/auth

Environment-Based Naming​

Using --environment takes precedence over branch names:

carlin deploy --environment staging
# Creates: my-app-staging (regardless of branch)

carlin deploy --environment production
# Creates: my-app-production (regardless of branch)

Environment-based stacks also enable:

  • Termination protection (automatic for production)
  • Environment-specific configurations
  • Clearer deployment separation

Stack Name Sanitization​

Branch names (and other inputs) may contain characters that are not allowed in CloudFormation stack names. carlin automatically sanitizes the generated name to ensure it satisfies the CloudFormation constraint [a-zA-Z][-a-zA-Z0-9]*:

  1. Unicode normalization: Accented characters are decomposed and their diacritical marks are stripped, mapping them to ASCII equivalents (e.g. configuração → configuracao, não → nao).
  2. Invalid character replacement: Any remaining character that is not a letter, digit, or hyphen is replaced with a hyphen.
  3. Hyphen collapsing: Consecutive hyphens are collapsed into a single hyphen, and leading/trailing hyphens are removed.
  4. Digit-start fix: If the resulting name starts with a digit, a Stack- prefix is added to satisfy the CloudFormation requirement that names begin with a letter.

Example with non-ASCII branch name​

# On branch: 1356-adicionar-configuração-para-não-adicionar-sufixos
carlin deploy
# Stack name becomes: OneclickadsGraphApi-1356-adicionar-configuracao-para-nao-adicionar-sufixos

Stack Name Constraints​

CloudFormation stack names must:

  • Be unique per AWS account and region
  • Contain only alphanumeric characters and hyphens
  • Be 128 characters or less
  • Start with an alphabetic character

carlin enforces a 100-character limit for AppSync API compatibility (AWS AppSync uses stack names for API names).

Non-ASCII Character Normalization​

Branch names containing non-ASCII characters (e.g. accented letters in Portuguese or Spanish) are automatically normalized so the resulting stack name satisfies the CloudFormation [a-zA-Z][-a-zA-Z0-9]* constraint:

  1. Unicode characters are decomposed using NFKD normalization (e.g. ç → c + combining cedilla).
  2. Combining diacritical marks are removed, leaving the base ASCII letter.
  3. Any remaining characters that are not letters, digits, or hyphens are replaced with a hyphen.
  4. Consecutive hyphens are collapsed into a single hyphen and leading/trailing hyphens are stripped.
  5. If the name would start with a digit after normalization, it is prefixed with Stack-.
  6. If normalization produces an empty string, Stack is used as a fallback.

Example (branch names with Portuguese characters):

# Branch: 1356-adicionar-configuração-para-não-adicionar-os-sufixos
# Package: @oneclickads/graph-api
carlin deploy
# Stack: OneclickadsGraphApi-1356-adicionar-configuracao-para-nao-adicionar-os-sufixos
caution

Changing the automatically generated stack name creates or updates a different CloudFormation stack. Use --stack-name only when you intentionally want to target a specific stack.

Configuration Priority​

Stack name resolution priority (highest to lowest):

  1. --stack-name CLI option
  2. stackName in carlin.yml
  3. CARLIN_STACK_NAME environment variable
  4. Automatic generation (package + environment/branch)

Common Patterns​

Multi-Environment Strategy​

# Development (feature branches)
carlin deploy
# Stack: my-app-feature-name

# Staging (shared environment)
carlin deploy --environment staging
# Stack: my-app-staging

# Production (protected environment)
carlin deploy --environment production
# Stack: my-app-production

Monorepo with Multiple Stacks​

// package.json
{
  "name": "@company/api"
}
# API stack
carlin deploy --environment production
# Stack: api-production

# Different service in same repo
cd ../workers
carlin deploy --environment production
# Stack: workers-production

Fixed Infrastructure Stack​

# VPC shared across all environments
carlin deploy --stack-name company-vpc --template-path infrastructure/vpc.ts

# All projects reference this VPC

Stack Name Algorithm​

When --stack-name is not provided, carlin builds the stack name from the package name and the selected environment or Git branch. The generated value is sanitized for CloudFormation by removing unsupported characters, normalizing non-ASCII text, collapsing repeated hyphens, and prefixing Stack- when the name would otherwise start with a number.

Troubleshooting​

Stack Name Conflicts​

Problem: Different branches create the same stack name.

Solution: Use explicit stack names or environments:

carlin deploy --stack-name unique-name
# or
carlin deploy --environment feature-1

Stack Already Exists​

Problem: Deploying to a branch that already has a stack.

Solution: This is expected behavior. carlin updates the existing stack instead of creating a new one.

Cannot Delete Stack​

Problem: Stack has termination protection enabled.

Solution: Disable termination protection in AWS Console or deploy without --environment:

# This won't work if environment is set
carlin deploy --destroy --environment production

# This works (removes environment constraint)
carlin deploy --destroy --stack-name my-app-production