1.3 Source Control Workflows, Webhooks & Branching Models

Modern Source Control Integration with AWS CodeConnections

Connecting external Version Control Systems (VCS)—such as GitHub, GitHub Enterprise Server, Bitbucket Cloud, or GitLab—to AWS CI/CD pipelines historically required personal access tokens (PATs) or static webhook secrets. Modern AWS architectures utilize AWS CodeStar Connections (now officially known as AWS CodeConnections), which provides managed, OAuth-based integrations with external source providers.

The CodeConnections Resource Lifecycle

A CodeConnection is a regional AWS resource (AWS::CodeStarConnections::Connection) that acts as an authenticated bridge between AWS and your source repository provider:

1. Resource Provisioning: The connection is provisioned via AWS CloudFormation, the AWS CLI, or the AWS Management Console.
2. Initial Status (PENDING): When created via CloudFormation or CLI, the connection is in a PENDING state. It cannot yet access repositories.
3. Interactive Handshake: An administrator must log into the AWS Management Console, navigate to the connection, and initiate the OAuth handshake. This installs the AWS GitHub App or Bitbucket App into the source control organization and authorizes repository access.
4. Active Status (AVAILABLE): Once authorized, the status transitions to AVAILABLE, and downstream CodePipeline source actions can bind to the connection using its Amazon Resource Name (ARN).

{
  "ActionTypeId": {
    "Category": "Source",
    "Owner": "AWS",
    "Provider": "CodeStarSourceConnection",
    "Version": "1"
  },
  "Name": "GitHubSource",
  "Configuration": {
    "ConnectionArn": "arn:aws:codestar-connections:us-east-1:111111111111:connection/a1b2c3d4-5678-90ef-ghij-1234567890ab",
    "FullRepositoryId": "enterprise-org/payment-service",
    "BranchName": "main",
    "OutputArtifactFormat": "CODE_ZIP",
    "DetectChanges": "true"
  },
  "OutputArtifacts": [
    {
      "Name": "SourceOutput"
    }
  ],
  "RunOrder": 1
}

---

Trigger Mechanisms: Webhooks vs. EventBridge Rules

Older pipelines utilized HTTP webhooks managed directly within GitHub or Bitbucket settings. Modern AWS architectures rely on Amazon EventBridge to achieve reliable, decoupled, event-driven pipeline execution.

EventBridge Rule Pattern for CodeConnections

When code is pushed to a connected repository, CodeConnections publishes an event to the default EventBridge bus. An EventBridge rule filters these events and invokes CodePipeline as its target:

{
  "source": ["aws.codestar-connections"],
  "detail-type": ["CodeConnections Source Event"],
  "detail": {
    "event": ["referenceCreated", "referenceUpdated"],
    "repositoryId": ["enterprise-org/payment-service"],
    "referenceName": ["main"],
    "referenceType": ["branch"]
  }
}

Advantages of EventBridge Over Direct Webhooks

• Resilience: EventBridge provides built-in retries, dead-letter queues (DLQs), and event replay capabilities if downstream pipeline targets experience transient throttling.
• Multiple Targets: A single Git push event can trigger multiple independent targets concurrently—such as invoking a CodePipeline deployment, triggering an auditing Lambda function, and posting an event to an Amazon SNS topic.
• Fine-Grained Filtering: EventBridge event patterns filter by branch name, tag prefix, or author identity without modifying the source control repository webhook configuration.

---

Branching Strategies and Pipeline Topologies

How teams branch and merge code directly dictates how CI/CD pipelines should be structured across environments.

Trunk-Based Development vs. GitFlow

In high-performing DevOps teams, trunk-based development is preferred because it eliminates long-lived drift. When a developer merges into main, the primary pipeline automatically tests, packages, and deploys the change through staging to production.

Ephemeral "Pipeline-per-Branch" with AWS CDK

For teams requiring dedicated preview environments for active feature branches, organizations implement Pipeline-per-Branch automation:

1. A developer creates a new feature branch (feature/user-auth).
2. An EventBridge rule detects the branch creation event (referenceCreated).
3. An AWS Lambda function executes an AWS Cloud Development Kit (CDK) or CloudFormation StackSet deployment that provisions an isolated, temporary CI/CD pipeline and ephemeral ECS/Fargate environment.
4. When the branch is deleted (referenceDeleted), EventBridge triggers a teardown Lambda function that destroys the stack and associated resources.

---

Automated Pull Request (PR) Validation Workflows

Deploying code to production from a feature branch is dangerous, but merging unvalidated code into main compromises the mainline. Teams implement automated pull request validation gates to verify code quality before merging.

[ Developer opens Pull Request ] ──> [ GitHub / Bitbucket ]
                                           │
                                    Emits PR Event
                                           │
                                           ▼
                             [ Amazon EventBridge Default Bus ]
                                           │
                                           ▼
                             [ Isolated AWS CodeBuild Project ]
                             - Runs Linters & Unit Tests
                             - Executes SAST Security Scanners
                                           │
                                           ▼
                             [ ReportBuildStatus to VCS ]
                                           │
                                           ▼
                               [ GitHub Branch Protection ]
                               (Blocks merge if checks fail)

Implementation Architecture

1. Event Trigger: When a pull request is opened or updated, the VCS provider emits a pull request event. CodeConnections or a GitHub Webhook forwards this to EventBridge.
2. Isolated Validation Project: EventBridge triggers an AWS CodeBuild project directly (bypassing CodePipeline entirely, since no deployment is occurring).
3. Test Execution: CodeBuild executes unit tests, linting, formatting checks, and static application security testing (SAST).
4. Status Reporting: The CodeBuild project is configured with reportBuildStatus: true or uses a Lambda function to invoke the GitHub Status API (POST /repos/{owner}/{repo}/statuses/{sha}). It reports pending, success, or failure.
5. VCS Branch Protection: Repository branch protection rules on main require the CodeBuild status check to pass before the merge button is enabled.

---

Mono-Repository Path-Filtering Architectures

Many enterprises consolidate multiple microservices, shared libraries, and infrastructure templates into a single mono-repository (mono-repo):

repo-root/
├── services/
│   ├── auth-service/        <-- Microservice 1
│   ├── billing-service/     <-- Microservice 2
│   └── notification-service/<-- Microservice 3
└── infrastructure/          <-- Shared CloudFormation/CDK

The Mono-Repo Challenge in CodePipeline

By default, an AWS CodePipeline source action triggers a full execution whenever any commit is pushed to the target branch. In a mono-repo with 20 services, a one-line typo fix in auth-service would trigger all 20 pipelines concurrently, causing severe resource wastage, queue contention, and deployment delays.

The EventBridge + Lambda Path Evaluator Pattern

To achieve selective, directory-based pipeline triggering, organizations implement the Path Evaluator Architecture:

[ Developer pushes commit to main ]
                │
                ▼
  [ AWS CodeConnections / EventBridge ]
                │
                ▼
   [ EventBridge Rule (Push Event) ]
                │
                ▼
   [ AWS Lambda (Path Evaluator) ]
   1. Calls VCS API (Compare Commits / git diff-tree)
   2. Evaluates modified file paths
   3. Determines affected services
                │
     ┌──────────┴──────────┐
     ▼                     ▼
[ StartPipeline: Auth ]  [ StartPipeline: Billing ]
(Only if /auth altered) (Only if /billing altered)

1. Disable Native Triggers: In CodePipeline, set DetectChanges: false on the source action, or avoid creating default EventBridge rules pointing directly to the pipelines.
2. Event Capture: An EventBridge rule captures all push events on the main branch and routes them to an AWS Lambda evaluator function.
3. Git Diff Analysis: The Lambda function receives the commit SHA and uses the GitHub/Bitbucket REST API (or clones shallow commit metadata) to run:

   git diff-tree -r --no-commit-id --name-only <before_sha> <after_sha>
   

4. Target Routing: Lambda maps the modified paths against a service routing table:
   • Changes under services/auth-service/** -> trigger CodePipeline-AuthService.
   • Changes under services/billing-service/** -> trigger CodePipeline-BillingService.
5. Pipeline Invocation: Lambda calls the CodePipeline SDK (codepipeline.startPipelineExecution({ name: 'CodePipeline-AuthService' })) only for the affected microservices.

Native CodePipeline V2 Trigger Filters

AWS CodePipeline V2 supports native Trigger Filters. You can configure Git tags and file path patterns directly within the pipeline source action trigger definition:

{
  "triggers": [
    {
      "providerType": "CodeStarSourceConnection",
      "gitConfiguration": {
        "sourceActionName": "Source",
        "push": [
          {
            "branches": {
              "includes": ["main"]
            },
            "filePaths": {
              "includes": ["services/auth-service/**"],
              "excludes": ["services/auth-service/docs/**", "**/*.md"]
            }
          }
        ]
      }
    }
  ]
}

This native feature eliminates the need for a custom Lambda evaluator when using CodePipeline V2, filtering out documentation changes and targeting specific service directories natively.