CodePipelineBuilder¶

Purpose¶

The CodePipelineBuilder is a concrete implementation of the AbstractAWSResourceBuilder designed to create AWS CodePipeline workflows for comprehensive CI/CD automation. This builder creates production-ready pipelines with multiple usage patterns (BUILD_RELEASE, BUILD_DEPLOY, DEPLOY), automated git integration, artifact management, cross-account deployment capabilities, and comprehensive stage orchestration for enterprise software delivery workflows.

Dependencies¶

Required AWS Permissions¶

CodePipeline Management: Create, configure, and manage CodePipeline workflows and stages
CodeCommit Integration: Access git repositories and monitor branch changes for automatic triggering
CodeBuild Integration: Execute build projects and manage build artifacts within pipeline stages
S3 Operations: Store and retrieve pipeline artifacts, deploy static content to S3 buckets
CloudFormation Deployment: Create and update infrastructure stacks through pipeline automation
IAM Role Management: Create service roles and configure cross-account deployment permissions
EventBridge Rules: Create automated pipeline triggers based on repository changes
KMS Operations: Encrypt and decrypt pipeline artifacts and cross-account resource access
CodeArtifact Access: Retrieve packages and dependencies from private artifact repositories
Resource Tagging: Apply organizational tags to pipeline resources for governance and cost allocation

Foundation Dependencies¶

Git Repositories: CodeCommit repositories containing source code and infrastructure templates
CodeBuild Projects: Pre-configured build projects for compilation, testing, and deployment automation
S3 Buckets: Artifact storage buckets for pipeline artifacts and release distribution buckets
IAM Roles: Action roles for pipeline execution and deployment roles for CloudFormation operations
VPC Infrastructure: Network configuration for CodeBuild projects and deployment targets
Cross-Account Setup: IAM roles and policies for multi-account deployment workflows
Environment Configuration: Account and region mappings for multi-environment deployments
Naming Standards: Organizational resource naming conventions following company patterns
Tagging Strategy: Consistent tagging for cost allocation, security policies, and operational categorization

Configuration¶

The builder validates all configuration through the CodePipelineConfig model, which becomes the authoritative source for all pipeline settings.

Usage¶

This builder expects that you dynamically set its configuration values in your CDK stack (it does not read them from the cdk.json) Here’s an example of how to use the CodePipelineBuilder to create a pipeline in a CDK stack:

BUILD_RELEASE Pattern¶

Builds artifacts from source code and publishes them to release repositories for later deployment.

{
  "usage": "BUILD_RELEASE",
  "git_provider": "CODECOMMIT",
  "git_repo": "codecommit_repository_object",
  "git_branch": "main",
  "is_dev_branch": false,
  "artifact_bucket": "pipeline_artifacts_bucket",
  "release_bucket": "releases_bucket", 
  "restart_execution_on_update": true,
  "stages": {
    "control": {
      "security-scan": {
        "run_order": 1,
        "build_project": "security_scanner_project",
        "output_names": ["SecurityReport"]
      }
    },
    "manual_approval": true,
    "build": {
      "compile-test": {
        "run_order": 1,
        "build_project": "build_project",
        "output_names": ["BuildArtifacts", "TestResults"]
      }
    },
    "release": {
      "publish-artifacts": {
        "run_order": 1,
        "action_type": "S3",
        "artifact_id": "compile-test"
      }
    }
  }
}

BUILD_DEPLOY Pattern¶

Builds artifacts and immediately deploys them to target environments.

{
  "usage": "BUILD_DEPLOY",
  "git_provider": "CODECOMMIT",
  "git_repo": "codecommit_repository_object",
  "git_branch": "develop",
  "is_dev_branch": true,
  "artifact_bucket": "pipeline_artifacts_bucket",
  "stages": {
    "self_mutate": {
      "update-pipeline": {
        "run_order": 1,
        "build_project": "pipeline_update_project"
      }
    },
    "build": {
      "build-and-test": {
        "run_order": 1,
        "build_project": "build_test_project",
        "output_names": ["DeploymentArtifacts"]
      }
    },
    "deploy": {
      "deploy-infrastructure": {
        "run_order": 1,
        "action_type": "CLOUDFORMATION",
        "artifact_id": "build-and-test",
        "action_role": "deployment_action_role",
        "deployment_role": "cloudformation_execution_role",
        "stack_name": "app-infrastructure",
        "stack_base_path": "cloudformation",
        "deploy_env": "staging"
      },
      "deploy-application": {
        "run_order": 2,
        "action_type": "CLOUDFORMATION",
        "artifact_id": "build-and-test",
        "action_role": "deployment_action_role",
        "deployment_role": "cloudformation_execution_role",
        "stack_name": "app-services",
        "stack_base_path": "cloudformation",
        "deploy_env": "staging"
      }
    }
  }
}

DEPLOY Pattern¶

Deploys pre-built artifacts from release repositories to production environments.

{
  "usage": "DEPLOY",
  "git_provider": "CODECOMMIT",
  "git_repo": "deployment_config_repository",
  "git_branch": "main",
  "is_dev_branch": false,
  "release_bucket": "releases_bucket",
  "target_env": "production",
  "stages": {
    "manual_source": {
      "fetch-release": {
        "run_order": 1,
        "build_project": "artifact_fetcher_project",
        "output_names": ["ProductionArtifacts"]
      }
    },
    "deploy": {
      "deploy-to-production": {
        "run_order": 1,
        "action_type": "CLOUDFORMATION",
        "artifact_id": "fetch-release",
        "action_role": "production_action_role",
        "deployment_role": "production_cloudformation_role",
        "stack_name": "app-production",
        "stack_base_path": "infrastructure",
        "deploy_env": "production"
      }
    }
  }
}

Configuration Parameters¶

Core Pipeline Configuration¶

Parameter	Mandatory	Type	Default	Description
usage	Yes	Usage		Pipeline pattern (BUILD_RELEASE, BUILD_DEPLOY, DEPLOY)
stages	Yes	StagesConfig		Complete stage configuration with actions
restart_execution_on_update	Yes	bool	True	Restart pipeline when updated
git_provider	Yes	GitProvider		Git provider (currently CODECOMMIT only)
git_repo	Yes	codecommit.IRepository		Source code repository
git_branch	Yes	str		Git branch to monitor for changes
is_dev_branch	Yes	bool		Development branch flag for build behavior
artifact_bucket	Yes (if BUILD_RELEASE or BUILD_DEPLOY)	s3.IBucket	None	S3 bucket for the build artifacts
release_bucket	Yes (if BUILD_RELEASE or DEPLOY)	s3.IBucket	None	S3 bucket for the release artifacts
target_env	Yes (if DEPLOY)	bool	None	Target environment for deployment

Stage Configuration Options¶

Stage Type	Usage Patterns	Required Actions	Description
source	All	Auto-generated	Git repository polling (automatic)
manual_source	DEPLOY only	CodeBuild projects	Manual artifact fetching
control	BUILD_RELEASE only	CodeBuild projects	Security scanning and validation
manual_approval	All	Boolean flag	Manual approval gate
self_mutate	BUILD_DEPLOY only	CodeBuild projects	Pipeline self-update
build	BUILD_RELEASE, BUILD_DEPLOY	CodeBuild projects	Compilation and testing
release	BUILD_RELEASE only	S3 or CodeBuild	Artifact publishing
publish	All	CodeBuild projects	Package/image publishing
deploy	BUILD_DEPLOY, DEPLOY	CloudFormation, S3, CodeBuild	Environment deployment

Please check the following models to have a detailed view on the configuration of the Stages and StageItems:

Usage¶

Here's an example of how to use the CodePipelineBuilder to build CodePipeline workflows in a CDK stack:

pipeline_builder = CodePipelineBuilder()
build_release_pipeline = pipeline_builder.set_application_helper(app_helper) \
                                        .set_builder_config(build_release_config) \
                                        .set_usage(Usage.BUILD_RELEASE) \
                                        .build(scope_from_stack)

deploy_builder = CodePipelineBuilder()
build_deploy_pipeline = deploy_builder.set_application_helper(app_helper) \
                                     .set_builder_config(build_deploy_config) \
                                     .set_usage(Usage.BUILD_DEPLOY) \
                                     .build(scope_from_stack)

Behavior and Features¶

Automatic Pipeline Configuration¶

Source Integration and Triggering:¶

EventBridge Automation: Automatic pipeline triggering on git repository changes
Branch Monitoring: Configurable branch monitoring with pattern-based filtering
Source Artifacts: Automatic source code artifact creation and variable injection
Cross-Repository Support: Multiple repository integration for complex workflows

Stage Orchestration and Dependencies:¶

Usage-Based Stages: Automatic stage creation based on usage pattern requirements
Artifact Flow Management: Intelligent artifact routing between stages with dependency resolution
Parallel Execution: Run order-based parallel and sequential action execution
Cross-Stage Inputs: Extra input artifact management for complex dependencies

Security and Access Control:¶

IAM Role Automation: Automatic service role creation with least-privilege permissions
Cross-Account Deployment: Support for multi-account deployment workflows
KMS Integration: Automatic artifact encryption and cross-account key management
EventBridge Security: Secure pipeline triggering with dedicated service roles

Naming Convention¶

Pipeline resources follow the pattern: {organization-prefix}-{app-name}-{target-env}-{branch}

The builder automatically:

Applies organizational naming standards
Includes branch identifiers for multi-branch workflows
Truncates names to respect AWS CodePipeline limits
Generates unique CloudFormation logical IDs

Stage Types and Behaviors¶

Source Stage (Automatic):¶

CodeCommit Integration: Automatic polling with EventBridge trigger creation
Variable Injection: Source phase variables for downstream stage access
Artifact Creation: Primary source artifact for all downstream stages
Branch Isolation: Branch-specific pipeline triggering and isolation

Control Stage (BUILD_RELEASE only):¶

Security Validation: Security scanning and compliance checking
Quality Gates: Code quality analysis and threshold enforcement
Artifact Inspection: Source code analysis and vulnerability assessment
Pipeline Gating: Conditional pipeline progression based on validation results

Manual Approval Stage (Optional):¶

Human Gates: Manual approval requirements for production deployments
Notification Integration: Automatic approval request notifications
Stage Positioning: Flexible positioning within pipeline workflow
Conditional Approval: Environment-specific approval requirements

Self-Mutate Stage (BUILD_DEPLOY only):¶

Pipeline Updates: Automatic pipeline configuration updates from source
Infrastructure Evolution: Self-updating pipeline infrastructure
Configuration Drift: Automatic detection and correction of configuration changes
Version Management: Pipeline version control and rollback capabilities

Build Stage (BUILD_RELEASE, BUILD_DEPLOY):¶

Compilation Workflows: Multi-language build support with artifact generation
Testing Integration: Unit testing, integration testing, and quality analysis
Artifact Generation: Multiple output artifact creation for different deployment targets
Environment Variables: Automatic injection of branch and environment context

Release Stage (BUILD_RELEASE only):¶

Artifact Publishing: S3-based artifact distribution and versioning
Registry Integration: Container registry and package repository publishing
Metadata Management: Release metadata and version tagging
Distribution Control: Multi-environment artifact distribution strategies

Deploy Stage (BUILD_DEPLOY, DEPLOY):¶

CloudFormation Integration: Infrastructure-as-code deployment automation
Multi-Stack Deployment: Sequential and parallel stack deployment coordination
Environment Targeting: Environment-specific configuration and parameter management
Rollback Capabilities: Automatic rollback on deployment failures

Action Types and Configuration¶

CodeBuild Actions:¶

Project Integration: Seamless integration with pre-configured CodeBuild projects
Environment Variables: Automatic injection of pipeline context and custom variables
Artifact Management: Input and output artifact coordination across pipeline stages
Build Environments: Support for various compute types and custom build images

CloudFormation Actions:¶

Template Management: Automatic template path resolution and parameter injection
Role Separation: Distinct action and deployment roles for security isolation
Capability Management: Automatic CloudFormation capability configuration
Parameter Injection: Environment-specific parameter management and substitution

S3 Deploy Actions:¶

Static Content: Website and static asset deployment automation
Artifact Distribution: Release artifact publishing and distribution
Bucket Management: Automatic bucket policy and access configuration
Content Extraction: Automatic artifact extraction and deployment

Environment Variable Management¶

Automatic Variables:¶

{
  "IS_DEV_BRANCH": "true/false based on is_dev_branch flag",
  "GIT_BRANCH": "configured git branch name",
  "SOURCE_PHASE_VARS": "source phase emitted variables namespace"
}

Custom Variables:¶

action_env_vars = {
    "ENVIRONMENT": codebuild.BuildEnvironmentVariable(
        value="production",
        type=codebuild.BuildEnvironmentVariableType.PLAINTEXT
    ),
    "DATABASE_URL": codebuild.BuildEnvironmentVariable(
        value="/app/database/url",
        type=codebuild.BuildEnvironmentVariableType.PARAMETER_STORE
    ),
    "API_SECRET": codebuild.BuildEnvironmentVariable(
        value="prod/api/secret",
        type=codebuild.BuildEnvironmentVariableType.SECRETS_MANAGER
    )
}

Artifact Management¶

Artifact Naming Patterns:¶

Source Artifacts: {org-pattern}-Source-Output
Build Artifacts: Custom names via output_names or {item-name}-output
Deploy Artifacts: {item-name}-output for deployment tracking

Artifact Dependencies:¶

Primary Input: Source artifact or specified artifact_id from previous stages
Extra Inputs: Additional artifacts via extra_inputs configuration
Cross-Stage Flow: Intelligent artifact routing between pipeline stages

Artifact Storage:¶

Encryption: Automatic KMS encryption for cross-account access
Retention: Configurable retention policies through S3 lifecycle management
Versioning: Automatic artifact versioning for rollback capabilities

Resource Outputs¶

Automatic Resource Creation¶

The builder automatically creates the following AWS resources:

Resource Type	Purpose	Naming Pattern
CodePipeline	Main CI/CD workflow execution	`{org-pattern}-{target-env}-{branch}`
IAM Role (Pipeline)	Pipeline execution permissions	`{org-pattern}-{env}-{branch}-role`
IAM Role (EventBridge)	Pipeline triggering permissions	`{org-pattern}-{env}-{branch}-event-role`
EventBridge Rule	Automatic git change detection	`{org-pattern}-{env}-{branch}-event-rule-codecommit-trigger`
Artifacts	Pipeline artifact coordination	`{stage-item-name}-output` or custom names

Cross-Account Integration¶

IAM Role Configuration:¶

Pipeline Role: Comprehensive permissions for S3, CodeBuild, CloudFormation access
Cross-Account Keys: Automatic KMS key configuration for multi-account workflows
Service Principals: Proper service principal configuration for all AWS services
Policy Statements: Least-privilege permissions for CodeArtifact and KMS operations

EventBridge Automation:¶

Repository Monitoring: Branch-specific change detection and filtering
Event Patterns: Precise event filtering for repository state changes
Target Configuration: Secure pipeline triggering with dedicated service roles
Cross-Region Support: Event routing across AWS regions when required

Notes

the set_usage method from the abstract class must be used in this builder. Usage must be one of: Usage.BUILD_RELEASE, Usage.BUILD_DEPLOY, Usage.DEPLOY from the Usage enum provided by the mare_aws_common_lib package.