AWS CDK CodeStar (Alpha)

Common errors

• ModuleNotFoundError: No module named 'aws_cdk.aws_codestar_alpha'

  cause The `aws-cdk-aws-codestar-alpha` package is not installed or the Python environment is incorrect.
  fix Run `pip install aws-cdk-aws-codestar-alpha` and ensure you are using the correct Python environment where it's installed.

• jsii.errors.JavaScriptError: TypeError: Cannot read properties of undefined (reading 'someProperty')

  cause This often occurs in alpha modules when an expected property is missing, or the API has changed. It's a common symptom of using an outdated construct definition or missing a required attribute.
  fix Consult the latest AWS CDK API documentation for `aws_cdk.aws_codestar_alpha` to verify construct properties and their types. Ensure all required properties are provided.

• TypeError: __init__ missing 1 required positional argument: 'scope'

  cause This error typically indicates that a CDK construct or stack constructor is being called incorrectly, missing the `scope` (parent construct) argument.
  fix Ensure you are passing the `self` (or another valid parent construct) as the first argument to the construct's `__init__` method, followed by an `id` and optional keyword arguments: `MyConstruct(self, 'MyId', ...)`.

• Validation failed with following errors: [The 'repositoryAccessToken' property requires a value.]

  cause For L1 constructs like `CfnGitHubRepository`, all required CloudFormation properties must be explicitly provided, including sensitive ones like access tokens.
  fix Provide a valid, non-empty value for `repository_access_token` (and other required properties) to the `CfnGitHubRepository` construct. Use environment variables or Secrets Manager for sensitive data.

Warnings

• breaking This module is in 'alpha' status. Its APIs are unstable, subject to breaking changes without major version bumps, and should not be used in production environments.
  Fix: Review release notes for each update. Pin exact alpha versions to avoid unexpected changes. Plan for refactoring if upgrading.
• gotcha Alpha modules often initially provide only L1 (CloudFormation-level) constructs (prefixed with `Cfn`). These require detailed, low-level configuration and may not offer the higher-level abstractions found in stable L2 constructs.
  Fix: Carefully review the construct's properties in the AWS CDK API documentation. Be prepared to provide all required CloudFormation properties directly. Consider using a stable CDK service module if L2 constructs are required.
• breaking AWS CDK v1 and v2 are incompatible. Alpha constructs like `aws-cdk-aws-codestar-alpha` are built for CDK v2 and require `aws-cdk-lib` (v2) as a dependency. Attempting to use them with CDK v1 will result in errors.
  Fix: Ensure your project's `aws-cdk-lib` dependency is at version 2.x.x. Use `pip freeze | grep aws-cdk` to verify.
• gotcha CDK deployments often fail due to insufficient AWS IAM permissions for the default roles, especially when creating or modifying specialized resources like CodeStar projects or connections.
  Fix: Ensure the IAM role used by CDK (often `cdk-hnb659fds` for `cdk deploy` or your execution role) has the necessary permissions for AWS CodeStar and any related services (e.g., IAM, CloudFormation, CodeBuild, CodePipeline, S3). Check CloudTrail logs for specific access denied errors.

Install

• pip install aws-cdk-aws-codestar-alpha Install the alpha construct
• pip install aws-cdk-lib Install core CDK library (if not already)

Imports

• CodeStarAlpha
  wrong:

  from aws_cdk.aws_codestar import Project

  correct:

  import aws_cdk.aws_codestar_alpha as codestar_alpha

  Alpha modules use a distinct import path (`_alpha`) and often contain only L1 CloudFormation constructs (prefixed `Cfn`) before L2 constructs are developed.
• App, Stack
  wrong:

  import aws_cdk.core as cdk

  correct:

  from aws_cdk import App, Stack, Environment

  CDK v2 changed core imports; `aws_cdk.core` is deprecated. Import `App`, `Stack`, `Environment` directly from `aws_cdk`.

Quickstart

This quickstart defines a basic CDK stack that includes a `CfnGitHubRepository` from the `aws-cdk-aws-codestar-alpha` module. Note that `CfnGitHubRepository` is an L1 (CloudFormation-level) construct and requires actual GitHub credentials (Personal Access Token) and repository details (owner, name) to be configured, typically via environment variables, for successful deployment. Remember to set `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION`.

import os
from aws_cdk import (
    App, Stack, Environment
)
import aws_cdk.aws_codestar_alpha as codestar_alpha

class MyCodeStarStack(Stack):
    def __init__(self, scope: App, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # IMPORTANT: This is an L1 CloudFormation construct. It requires
        # actual GitHub credentials and repository details for successful deployment.
        # Store sensitive data in environment variables or AWS Secrets Manager.
        github_access_token = os.environ.get("GITHUB_ACCESS_TOKEN", "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN")
        github_owner = os.environ.get("GITHUB_OWNER", "your-github-username")
        repository_name = os.environ.get("GITHUB_REPO_NAME", "my-codestar-repo")

        if github_access_token == "YOUR_GITHUB_PERSONAL_ACCESS_TOKEN":
            print("WARNING: GITHUB_ACCESS_TOKEN not set. This construct will likely fail deployment.")

        # Define a GitHub repository resource for CodeStar
        # This resource integrates an existing GitHub repo with AWS CodeStar.
        codestar_alpha.CfnGitHubRepository(self, "MyGitHubRepo",
            repository_name=repository_name,
            owner=github_owner,
            repository_access_token=github_access_token,
            # is_private=True, # Optional
            # repository_description="My CodeStar managed GitHub repository" # Optional
        )

app = App()
MyCodeStarStack(app, "MyCodeStarStack",
    env=Environment(account=os.environ.get("CDK_DEFAULT_ACCOUNT"), region=os.environ.get("CDK_DEFAULT_REGION"))
)
app.synth()