Refactor bootstrap process to accept AWS profile and region parameters

[jfrench9]

Summary

This PR refactors the bootstrap setup process to accept AWS profile and region as configurable arguments, improving the flexibility and usability of the development environment initialization.

Key Accomplishments

• Enhanced Bootstrap Flexibility: Modified the bootstrap process to accept AWS profile and region as command-line arguments, making it easier to work with different AWS environments
• Streamlined Setup Scripts: Significantly reduced complexity in GitHub Actions setup utilities (449 additions, 357 deletions net positive)
• Improved Workflow Configuration: Updated multiple GitHub Actions workflows to support the enhanced bootstrap parameters:
  • Create PR workflow
  • Release creation and tagging workflows
  • Graph maintenance workflow
• Simplified Build Process: Updated project build configuration to align with the new bootstrap interface

Breaking Changes

⚠️ Potential Breaking Change: The bootstrap process now requires explicit AWS profile and region parameters. Existing automation or documentation referencing the old bootstrap interface will need to be updated.

Testing Notes

• Verify bootstrap process works correctly with different AWS profiles and regions
• Test all affected GitHub Actions workflows to ensure they function with the updated parameters
• Confirm that existing development environments can be successfully recreated using the new bootstrap interface

Infrastructure Considerations

• This change affects the foundational setup process for the entire project
• Teams will need to update their local development setup procedures
• CI/CD pipelines have been updated to accommodate the new parameter requirements
• Consider updating project documentation to reflect the new bootstrap usage patterns

---

🤖 Generated with Claude Code

Branch Info:

• Source: chore/improve-bootstrap
• Target: main
• Type: chore

Co-Authored-By: Claude noreply@anthropic.com

[jfrench9]

@claude please review this PR

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[claude]

Claude finished @jfrench9's task in 2m 10s —— View job

---

PR Review: Bootstrap Process Refactoring

I've completed a thorough review of this PR. Here's my analysis:

---

✅ Strengths

1. Excellent Interface Improvement

The addition of profile and region parameters makes the bootstrap process much more flexible for teams working with multiple AWS accounts or regions. The default values (robosystems-sso, us-east-1) ensure backward compatibility.

# bin/setup/bootstrap.sh:45-47
SSO_PROFILE="${1:-${AWS_PROFILE:-robosystems-sso}}"
AWS_REGION="${2:-${AWS_REGION:-us-east-1}}"

Good: Proper precedence (CLI args → env vars → defaults)

2. Improved User Experience

• Auto-export of AWS profile/region (bin/setup/bootstrap.sh:50-53) ensures the script works immediately, even before .envrc is activated
• Smart .envrc handling with profile conflict detection and resolution
• Clear action-required messaging when .envrc needs activation

3. gha.sh Simplification

The massive reduction (449→126 lines) is excellent:

• Removed ~80 hardcoded GitHub variables in favor of workflow defaults
• New "essential config" mode requires only 5 variables (auto-detected!)
• Much better for forks and new deployments

4. Better Error Handling

# bin/setup/gha.sh:49-69
if ! command -v aws >/dev/null 2>&1; then
    echo ""
    return 0  # Return success to avoid set -e exit
fi

Good: Graceful degradation when AWS CLI is unavailable

5. Workflow Resilience

All GitHub Actions workflows now handle missing ACTIONS_TOKEN gracefully instead of failing silently.

---

⚠️ Issues & Recommendations

1. Critical: gha.sh VPC-only Deployment Bug

Location: bin/setup/gha.sh:233-250

When ROOT_DOMAIN is empty (VPC-only deployment), the script sets domain variables to empty strings:

gh variable set API_DOMAIN_NAME_ROOT --body ""
gh variable set API_DOMAIN_NAME_PROD --body ""

Problem: The setup_full_config() function still creates domain-derived variables even when ROOT_DOMAIN is empty, but setup_essential_config() only sets API_DOMAIN_NAME_ROOT. This creates an inconsistency.

Recommendation: In setup_full_config(), wrap all domain-related gh variable set commands in the same conditional block that already exists for other domain variables (lines 232-250). Example:

if [ -n "$ROOT_DOMAIN" ]; then
    gh variable set API_DOMAIN_NAME_ROOT --body "$ROOT_DOMAIN"
    gh variable set API_DOMAIN_NAME_PROD --body "api.$ROOT_DOMAIN"
    gh variable set API_DOMAIN_NAME_STAGING --body "staging.api.$ROOT_DOMAIN"
    # ... other domain vars
else
    gh variable set API_DOMAIN_NAME_ROOT --body ""
    gh variable set API_DOMAIN_NAME_PROD --body ""
    gh variable set API_DOMAIN_NAME_STAGING --body ""
fi

Fix this →

---

2. Medium: Missing Region Export in .envrc

Location: bin/setup/bootstrap.sh:90-155

The setup_direnv() function correctly adds AWS_REGION when creating .envrc, but when updating an existing .envrc that has the correct profile, it only adds the region if missing (line 110-114).

Edge case: If a user has an old .envrc with only AWS_PROFILE and runs bootstrap with a non-default region, the region won't be added.

Recommendation: Always verify and add/update AWS_REGION when the profile matches:

if [ "$current_profile" = "$expected_profile" ]; then
    print_success "Existing .envrc already configured for profile '${expected_profile}'"
    
    # Always ensure region is set correctly
    if grep -q "^export AWS_REGION=" "$target_file" 2>/dev/null; then
        # Update existing region if different
        current_region=$(grep -E "^export AWS_REGION=" "$target_file" | cut -d'=' -f2 | tr -d '"' | tr -d "'")
        if [ "$current_region" != "$expected_region" ]; then
            sed -i "s/^export AWS_REGION=.*/export AWS_REGION=${expected_region}/" "$target_file"
            print_info "Updated AWS_REGION to ${expected_region}"
            ENVRC_NEEDS_ACTIVATION=true
        fi
    else
        echo "export AWS_REGION=${expected_region}" >> "$target_file"
        print_info "Added AWS_REGION to existing .envrc"
        ENVRC_NEEDS_ACTIVATION=true
    fi
    return 0
fi

---

3. Low: Justfile Documentation Clarity

Location: justfile:344-349

The comment shows examples with profile/region but doesn't clarify what happens if you only provide one argument.

Recommendation: Add a note:

# Bootstrap AWS OIDC federation for GitHub Actions
# Usage: just bootstrap [profile] [region]
#   profile: AWS SSO profile name (default: robosystems-sso)
#   region:  AWS region (default: us-east-1)
# Examples:
#   just bootstrap                     # Use both defaults
#   just bootstrap my-profile          # Custom profile, default region
#   just bootstrap my-profile eu-west-1  # Custom profile and region

---

4. Low: Shell Error Handling Edge Case

Location: bin/setup/gha.sh:60

ami_id=$(aws ssm get-parameter \
    --name "$ssm_path" \
    --query "Parameter.Value" \
    --output text 2>/dev/null) || true

The || true prevents set -e from exiting, but if AWS CLI returns non-zero for reasons other than "parameter not found" (e.g., permission denied, invalid region), the script silently continues without logging the actual error.

Recommendation: Capture and log the error type:

local error_output
error_output=$(aws ssm get-parameter \
    --name "$ssm_path" \
    --query "Parameter.Value" \
    --output text 2>&1) || {
    # Check if it's just "not found" vs actual error
    if [[ "$error_output" == *"ParameterNotFound"* ]]; then
        echo "" # Not found is okay
    else
        >&2 echo "Warning: Failed to query SSM parameter: $error_output"
        echo ""
    fi
    return 0
}
ami_id="$error_output"

---

🔒 Security Review

✅ Good Security Practices:

1. No secrets exposed in parameters or defaults
2. Proper use of OIDC over long-lived credentials
3. ACTIONS_TOKEN is correctly treated as optional (workflows degrade gracefully)
4. AWS profile/region can be passed as arguments (no need to modify files)

⚠️ Minor Concern:

The .envrc file is created/modified without explicit user consent if it already exists with a different profile. While the script does ask (line 122), the error message on "No" could be clearer about the implications.

Current:

print_error "Cannot continue with mismatched profile"
print_info "Either update .envrc manually or run: just bootstrap ${current_profile}"

Suggestion: More helpful guidance:

print_error "Cannot continue with mismatched profile"
print_info "Options:"
print_info "  1. Update .envrc manually to use profile: ${expected_profile}"
print_info "  2. Run bootstrap with your current profile: just bootstrap ${current_profile} ${AWS_REGION}"
print_info "  3. Remove .envrc and re-run this command"

---

📊 Code Quality

Aspect	Rating	Notes
Code Clarity	⭐⭐⭐⭐⭐	Excellent comments, clear variable names
Error Handling	⭐⭐⭐⭐☆	Good overall, minor edge cases noted
Backward Compatibility	⭐⭐⭐⭐⭐	Defaults ensure no breaking changes
Testing Considerations	⭐⭐⭐☆☆	Could benefit from validation tests
Documentation	⭐⭐⭐⭐☆	Great inline docs, justfile could be clearer

---

🎯 Breaking Changes

The PR description correctly identifies this as a potential breaking change. However, due to the default values, this is actually backward compatible for:

• Users who don't pass arguments (defaults match old behavior)
• Users who have AWS_PROFILE and AWS_REGION environment variables set

Only breaks for: Custom automation that called bootstrap.sh with positional arguments for other purposes (unlikely).

---

📝 Testing Recommendations

Before merging, consider testing these scenarios:

1. ✅ Fresh bootstrap with defaults
2. ✅ Bootstrap with custom profile and region
3. ✅ Bootstrap when .envrc exists with same profile
4. ✅ Bootstrap when .envrc exists with different profile
5. ⚠️ VPC-only deployment (ROOT_DOMAIN empty) - test both essential and full config modes
6. ⚠️ Bootstrap with region argument but default profile
7. ✅ All GitHub Actions workflows with ACTIONS_TOKEN present
8. ✅ All GitHub Actions workflows with ACTIONS_TOKEN missing

---

✅ Verdict

Overall Assessment: APPROVE with minor fixes recommended

This is a high-quality refactoring that significantly improves the developer experience. The changes are well-thought-out, properly documented, and mostly backward compatible.

Must Fix Before Merge:

1. ⚠️ Issue Inital open source release of robosystems #1: VPC-only deployment domain variable consistency in gha.sh

Recommended but Optional:

2. Issue Fix MCP tools query results to include units and improve dimensions #2: Region update logic in .envrc handling
3. Issue Enhance SEC pipeline security and add reconsolidation support #3: Justfile documentation clarity
4. Issue chore: improve documentation and suppress build output #4: AWS SSM error logging improvement
5. Security: Better .envrc conflict resolution messaging

---

Great work on this refactoring! The reduction in complexity (especially in gha.sh) and the improved flexibility will make onboarding much smoother.

--- | Branch: chore/improve-bootstrap