docs: add developer's guide for running CodeBuild locally

[scottschreckengaust]

Summary

• Adds docs/DEVELOPERS_GUIDE.md with instructions for running CodeBuild locally using the local agent
• Documents all codebuild_build.sh flags including -b for buildspec overrides, -c for AWS credentials, and -e for environment variables
• Adds .codebuild/** to .gitignore for local build artifacts

Test plan

• Verify markdown renders correctly on GitHub
• Confirm codebuild_build.sh commands work locally with -b flag

🤖 Generated with Claude Code

[scottschreckengaust]

An alternative is including instructions in this GitHub Wiki. This is viable, but will not be pulled down while developing and could be missed.

https://github.com/awslabs/aidlc-workflows/wiki

I would argue that the Wiki should be disabled.

[harmjeff]

I have reviewed it and run it locally. Looks good

[raj-jain-aws]

Ran this. Got output but not sure how to interpret it. What should we be looking for?

agent-1  | 
agent-1  | [Container] 2026/03/10 00:30:25.798527 Phase complete: BUILD State: SUCCEEDED
agent-1  | [Container] 2026/03/10 00:30:25.798597 Phase context status code:  Message: 
agent-1  | [Container] 2026/03/10 00:30:25.813077 Entering phase POST_BUILD
agent-1  | [Container] 2026/03/10 00:30:25.822893 Running command echo "post_build ${TEST_ONE}" | tee --append ./codebuild.out
agent-1  | post_build 1
agent-1  | 
agent-1  | [Container] 2026/03/10 00:30:25.864239 Running command echo "Build completed with status $CODEBUILD_BUILD_SUCCEEDING"
agent-1  | Build completed with status 1
agent-1  | 
agent-1  | [Container] 2026/03/10 00:30:25.898186 Running command cat ./codebuild.out
agent-1  | install 1
agent-1  | pre_build 1
agent-1  | build 1
agent-1  | post_build 1
agent-1  | 
agent-1  | [Container] 2026/03/10 00:30:25.921089 Phase complete: POST_BUILD State: SUCCEEDED
agent-1  | [Container] 2026/03/10 00:30:25.921136 Phase context status code:  Message: 
agent-1  | [Container] 2026/03/10 00:30:25.946802 Expanding base directory path: .
agent-1  | [Container] 2026/03/10 00:30:25.951568 Assembling file list
agent-1  | [Container] 2026/03/10 00:30:25.951596 Expanding .
agent-1  | [Container] 2026/03/10 00:30:25.958629 Expanding file paths for base directory .
agent-1  | [Container] 2026/03/10 00:30:25.958656 Assembling file list
agent-1  | [Container] 2026/03/10 00:30:25.958659 Expanding **/codebuild.out
agent-1  | [Container] 2026/03/10 00:30:25.964005 Found 1 file(s)
agent-1  | [Container] 2026/03/10 00:30:25.975225 Preparing to copy secondary artifacts
agent-1  | [Container] 2026/03/10 00:30:25.975279 No secondary artifacts defined in buildspec
agent-1  | [Container] 2026/03/10 00:30:25.978919 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED
agent-1  | [Container] 2026/03/10 00:30:25.978975 Phase context status code:  Message: 
Aborting on container exit...
agent-1 exited with code 0
[+] Stopping 2/0
 ✔ Container agent-resources-build-1  Stopped0.0s 
 ✔ Container agent-resources-agent-1  Stopped0.0s 

[scottschreckengaust]

Ran this. Got output but not sure how to interpret it. What should we be looking for?

This shows that you have successfully run a local AWS CodeBuild. The four "phases" of the workflow outline the commands that will be run in order (install, pre_build, build, and post_build)

I updated the section of the build specification override to install the GitHub CLI, gh, set if the run is in a "release" (tagged)/"pre-release" (the default main branch)/"pre-merge" (any other non-default branch).

[harmjeff]

Reviewed with developers

[raj-jain-aws]

This PR adds AWS CodeBuild build scripts for aidlc-workflows. The build scripts are meant to run an evaluation framework where PRs are put through automated regression and evaluations. CodeBuild invocations are triggered from GitHub actions. Developers can also invoke build scripts from their local machines using https://github.com/nektos/act. act depends on Go runtime.

System Design

act command run output

Following the instructions in DEVELOPERS_GUIDE.md, I get the following results (only act command shown below but all instructions in DEVELOPERS_GUIDE.md were followed) --

jinraj@bcd07466740b aidlc-workflows % act --platform ubuntu-latest=-self-hosted \
    --job build \
    --workflows .github/workflows/codebuild.yml \
    --env-file .env \
    --var CODEBUILD_PROJECT_NAME=codebuild-project \
    --var AWS_REGION=us-east-1 \
    --var ROLE_DURATION_SECONDS=7200 \
    --artifact-server-path=$PWD/.codebuild/artifacts \
    --cache-server-path=$PWD/.codebuild/artifacts \
    --env ACT_CODEBUILD_DIR=$PWD/.codebuild/downloads \
    --bind
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' 
WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠  
INFO[0000] Start server on http://192.168.1.126:34567   
[CodeBuild/build] ⭐ Run Set up job
[CodeBuild/build]   ✅  Success - Set up job
[CodeBuild/build]   ☁  git clone 'https://github.com/actions/cache' # ref=cdf6c1fa76f9f475f3d7449005a359c84ca0f306

[CodeBuild/build]   ☁  git clone 'https://github.com/aws-actions/configure-aws-credentials' # ref=8df5847569e6427dd6c4fb1cf565c83acfa8afa7
[CodeBuild/build]   ☁  git clone 'https://github.com/aws-actions/aws-codebuild-run-build' # ref=d8279f349f3b1b84e834c30e47c20dcb8888b7e5
[CodeBuild/build]   ☁  git clone 'https://github.com/actions/cache' # ref=cdf6c1fa76f9f475f3d7449005a359c84ca0f306
[CodeBuild/build]   ☁  git clone 'https://github.com/actions/upload-artifact' # ref=b7c566a772e6b6bfb58ed0dc250532a479d7789f
[CodeBuild/build]   ☁  git clone 'https://github.com/actions/upload-artifact' # ref=b7c566a772e6b6bfb58ed0dc250532a479d7789f
[CodeBuild/build]   ☁  git clone 'https://github.com/actions/upload-artifact' # ref=b7c566a772e6b6bfb58ed0dc250532a479d7789f
[CodeBuild/build] ⭐ Run Main List caches

| Showing 2 of 2 caches in awslabs/aidlc-workflows
| 
| ID          KEY                    SIZE   CREATED             ACCESSED          
| 3185871324  codebuild-project-...  329 B  about 6 days ago    about 6 days ago
| 3273487564  codebuild-project-...  424 B  about 14 hours ago  about 14 hours ago
[CodeBuild/build]   ✅  Success - Main List caches [880.382125ms]
[CodeBuild/build] ⭐ Run Main Check cache
| Cache not found for input keys: codebuild-project-feature/developers-guide-fd66212e97297c9c43dad0620dbaccb2166852e6
[CodeBuild/build]   ✅  Success - Main Check cache [3.6224355s]
[CodeBuild/build]   ⚙  ::set-output:: cache-primary-key=codebuild-project-feature/developers-guide-fd66212e97297c9c43dad0620dbaccb2166852e6
[CodeBuild/build] ⭐ Run Main Configure AWS credentials
[CodeBuild/build]   ⚙  ***
[CodeBuild/build]   ❓  ::add-mask::arn:aws:sts::***:assumed-role/Admin/jinraj-Isengard
| Proceeding with IAM user credentials
[CodeBuild/build]   ✅  Success - Main Configure AWS credentials [3.516204667s]
[CodeBuild/build]   ⚙  ::set-env:: AWS_DEFAULT_REGION=us-east-1
[CodeBuild/build]   ⚙  ::set-env:: AWS_REGION=us-east-1
[CodeBuild/build]   ⚙  ::set-output:: aws-account-id=***
[CodeBuild/build]   ⚙  ::set-output:: authenticated-arn=arn:aws:sts::***:assumed-role/Admin/jinraj-Isengard
[CodeBuild/build] ⭐ Run Main Run CodeBuild
| *****STARTING CODEBUILD*****
[CodeBuild/build]   ❗  ::error::Project cannot be found: arn:aws:codebuild:us-east-1:***:project/codebuild-project
| *****CODEBUILD COMPLETE*****
[CodeBuild/build]   ❌  Failure - Main Run CodeBuild [1.767066625s]
[CodeBuild/build] exit status 1
[CodeBuild/build] ⭐ Run Main Build ID
| CodeBuild Build ID 
[CodeBuild/build]   ✅  Success - Main Build ID [78.21575ms]
[CodeBuild/build] ⭐ Run Post Configure AWS credentials
[CodeBuild/build]   ✅  Success - Post Configure AWS credentials [98.240584ms]
[CodeBuild/build]   ⚙  ::set-env:: AWS_SECRET_ACCESS_KEY=
[CodeBuild/build]   ⚙  ::set-env:: AWS_SESSION_TOKEN=
[CodeBuild/build]   ⚙  ::set-env:: AWS_DEFAULT_REGION=
[CodeBuild/build]   ⚙  ::set-env:: AWS_REGION=
[CodeBuild/build]   ⚙  ::set-env:: AWS_ACCESS_KEY_ID=
[CodeBuild/build] ⭐ Run Complete job
[CodeBuild/build]   ✅  Success - Complete job
[CodeBuild/build] 🏁  Job failed
Error: Job 'build' failed

[Kalindi-Dev]

Looks good to me

[scottschreckengaust]

act depends on Go runtime and requires sudo.

does not require sudo

[scottschreckengaust]

System Design

A manual gated approval is required to run in the environment by only administrators without self-review

[raj-jain-aws]

System Design

A manual gated approval is required to run in the environment by only administrators without self-review

@scottschreckengaust I see the PR has been merged. Have we found and fixed the issue I reported or were these because of my environment errors? Let me know if this is ready for retest and if these were my environment specific error how should I fix that.

[raj-jain-aws]

act depends on Go runtime and requires sudo.

does not require sudo

Updated that in my comment. It was Go runtime installation that required sudo.