Documentation
Manifest Reference

Manifest Reference

Complete reference for pipeline manifest configuration.

Pipeline Metadata

pipeline.yml
pipeline_name: My SAM Application Deployment
pipeline_description: Description of the pipeline
summary: |-
  Optional post-deployment summary shown in console

Pipeline Settings

Configure global settings that apply to all stacks:

pipeline.yml
pipeline_settings:
  stack_name_prefix: myapp-        # Prefix for all stack names
  default_region: us-east-1        # Default AWS region
  default_sam_config:              # Shared SAM configuration
    version: 0.1
    default:
      deploy:
        parameters:
          capabilities: CAPABILITY_IAM
          confirm_changeset: false
  output_masking:                  # Security-focused output masking
    enabled: true
    categories:
      account_ids: true            # Mask AWS account IDs
      api_endpoints: true          # Mask API Gateway URLs
      database_endpoints: true     # Mask database connection strings
  inputs:                          # Pipeline input parameters
    environment:
      type: string
      default: development

Stack Configuration

Define your deployment stacks:

pipeline.yml
stacks:
  - id: network                    # Unique stack identifier
    dir: infrastructure/network    # Directory containing SAM template
    if: ${{ env.DEPLOY_NETWORK }}  # Conditional deployment
    params:                        # Stack parameters
      Environment: ${{ inputs.environment }}
    run: |-                       # Post-deployment actions
      echo "Network deployed successfully"

Stack Properties

Required Properties

PropertyTypeDescription
idstringUnique identifier for the stack
dirstringDirectory containing the SAM template and code

Optional Properties

PropertyTypeDescription
namestringHuman-readable name for the stack
descriptionstringDescription of the stack
ifstringConditional expression for deployment
configstringPath for external SAM configuration file generation
paramsobjectParameters to pass to the stack
runstringCommands to run after deployment
regionstringAWS region override for this stack
profilestringAWS profile override for this stack
stack_name_suffixstringStack-specific suffix for naming
sam_config_overridesobjectStack-specific SAM configuration

External Configuration

Enable generation of standalone SAM configuration files using the config field:

pipeline.yml
stacks:
  - id: api
    dir: stacks/api/
    config: configs/production/api/  # External config directory
    params:
      Environment: production

Multi-Environment Example

pipeline.yml
pipeline_settings:
  inputs:
    environment:
      type: string
      default: dev

stacks:
  - id: backend
    dir: stacks/backend/
    config: configs/${{ inputs.environment }}/backend/
    params:
      Environment: ${{ inputs.environment }}
      LogLevel: ${{ inputs.environment == 'prod' && 'WARN' || 'DEBUG' }}

For complete documentation, see External Configuration.

Expression Language

samstacks supports GitHub Actions-style expressions:

Environment Variables 

params:
  Environment: ${{ env.ENVIRONMENT || 'development' }}

Stack Outputs 

params:
  VpcId: ${{ stacks.network.outputs.VpcId }}
  DatabaseUrl: ${{ stacks.database.outputs.ConnectionString }}

Input Parameters 

params:
  InstanceType: ${{ inputs.instance_type }}

Conditional Logic 

if: ${{ env.ENVIRONMENT == 'production' }}
if: ${{ inputs.deploy_database == 'true' }}

Mathematical Operations 

params:
  DesiredCapacity: ${{ inputs.base_capacity * 2 }}
  MaxSize: ${{ inputs.base_capacity + 10 }}

Complete Example

pipeline.yml
pipeline_name: Multi-Tier Application
pipeline_description: Web application with database and API

pipeline_settings:
  stack_name_prefix: myapp-
  default_region: us-west-2
  inputs:
    environment:
      type: string
      default: development

stacks:
  - id: network
    dir: infrastructure/network
    params:
      Environment: ${{ inputs.environment }}
      
  - id: database
    dir: infrastructure/database
    if: ${{ inputs.environment != 'test' }}
    params:
      VpcId: ${{ stacks.network.outputs.VpcId }}
      SubnetIds: ${{ stacks.network.outputs.PrivateSubnetIds }}
      
  - id: api
    dir: application/api
    params:
      DatabaseUrl: ${{ stacks.database.outputs.ConnectionString }}
      Environment: ${{ inputs.environment }}
    run: |-
      echo "API deployed to: ${{ stacks.api.outputs.ApiUrl }}"

Security Features

Output Masking

Protect sensitive information in deployment outputs:

pipeline.yml
pipeline_settings:
  output_masking:
    enabled: true                  # Master switch for all masking
    categories:
      account_ids: true            # AWS account IDs (12-digit numbers)
      api_endpoints: true          # API Gateway and Lambda Function URLs
      database_endpoints: true     # RDS, ElastiCache, DocumentDB endpoints
      load_balancer_dns: true      # ALB, NLB, CLB DNS names
      cloudfront_domains: true     # CloudFront distribution domains
      s3_bucket_domains: true      # S3 website and transfer endpoints
      ip_addresses: true           # IPv4 and IPv6 addresses
    custom_patterns:               # Application-specific patterns
      - pattern: "secret-[a-zA-Z0-9]+"
        replacement: "secret-***"
        description: "Mask secret tokens"

For complete documentation, see Security-Focused Output Masking.

Next Steps

External ConfigurationFAQ