Codecatalyst Diagnostics

Amazon CodeCatalyst Diagnostics

When to use

Any Amazon CodeCatalyst investigation — space creation, project configuration, workflow failures, action errors, dev environments, IDE connectivity, source repositories, pull requests, deployments, environment configuration, AWS connections, IAM roles, or blueprint errors.

Investigation workflow

Step 1 — Collect and triage

aws codecatalyst list-spaces
aws codecatalyst get-space --name <space-name>
aws codecatalyst list-projects --space-name <space-name>

Step 2 — Domain deep dive

aws codecatalyst get-project --space-name <space-name> --name <project-name>
aws codecatalyst list-workflow-runs --space-name <space-name> --project-name <project-name> --sort-by START_TIME
aws codecatalyst list-dev-environments --space-name <space-name> --project-name <project-name>

Step 3 — Detailed investigation

aws codecatalyst get-workflow-run --space-name <space-name> --project-name <project-name> --id <run-id>
aws codecatalyst get-dev-environment --space-name <space-name> --project-name <project-name> --id <env-id>
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=codecatalyst.amazonaws.com --max-results 20

Read references/guardrails.md before concluding on any CodeCatalyst issue.

Tool quick reference

Gotchas: Amazon CodeCatalyst

• CodeCatalyst uses AWS Builder ID for authentication, NOT IAM users. Builder ID is a separate identity system from AWS IAM.
• Spaces are the top-level organizational unit. They are NOT AWS accounts. A space can be connected to multiple AWS accounts.
• Workflows use YAML definitions similar to but NOT identical to GitHub Actions. Do not assume GitHub Actions syntax works directly.
• Dev environments are cloud-based compute instances. They have configurable instance types and storage but are NOT EC2 instances you manage.
• AWS connections link CodeCatalyst spaces to AWS accounts. They require an IAM role in the target account with a trust policy for CodeCatalyst.
• Blueprints are project templates. They generate initial project structure but do NOT continuously manage the project after creation.
• Source repositories in CodeCatalyst are managed Git repositories. They support linking to external repositories (GitHub, Bitbucket) but these are separate from CodeCatalyst-native repos.

Anti-hallucination rules

1. Always cite specific space names, project names, workflow run IDs, or API responses as evidence.
2. CodeCatalyst uses Builder ID, NOT IAM users. Never suggest IAM user login for CodeCatalyst.
3. Workflows are NOT GitHub Actions. Never assume GitHub Actions syntax or features.
4. Dev environments are NOT EC2 instances. Never suggest EC2 management commands.
5. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

14 runbooks