second first commit

2026-09-22 08:57:00 -04:00
parent e88d7e2ff3
commit 0aef7fb2d8
4766 changed files with 1236986 additions and 0 deletions
@@ -0,0 +1,124 @@
+# CodeBuild
+
+Floci implements the CodeBuild API — stored-state management plus real build execution inside Docker containers.
+
+**Protocol:** JSON 1.1 — `POST /` with `X-Amz-Target: CodeBuild_20161006.<Action>`
+
+**ARN formats:**
+
+- `arn:aws:codebuild:<region>:<account>:project/<name>`
+- `arn:aws:codebuild:<region>:<account>:report-group/<name>`
+- `arn:aws:codebuild:<region>:<account>:token/<type>-<uuid>`
+- `arn:aws:codebuild:<region>:<account>:build/<project>:<uuid>`
+
+## Supported Operations (20 total)
+
+### Projects
+
+| Operation | Notes |
+|---|---|
+| `CreateProject` | Stores project config; requires `name`, `source.type`, `artifacts.type`, `environment`, `serviceRole` |
+| `UpdateProject` | Partial update — only supplied fields are modified |
+| `DeleteProject` | Removes project by name |
+| `BatchGetProjects` | Returns found projects and a `projectsNotFound` list |
+| `ListProjects` | Returns all project names in the region |
+
+### Build Execution
+
+| Operation | Notes |
+|---|---|
+| `StartBuild` | Launches a real Docker container using the project's image; runs buildspec phases (`INSTALL`, `PRE_BUILD`, `BUILD`, `POST_BUILD`); returns immediately with `IN_PROGRESS` status |
+| `BatchGetBuilds` | Returns current build state; poll until `buildComplete` is `true` |
+| `ListBuilds` | Returns all build IDs in the region, most recent first |
+| `ListBuildsForProject` | Returns build IDs for a specific project |
+| `StopBuild` | Signals a running build to stop; build transitions to `STOPPED` |
+| `RetryBuild` | Starts a new build using the same config as a completed build; returns a new build record |
+
+### Report Groups
+
+| Operation | Notes |
+|---|---|
+| `CreateReportGroup` | Stores report group config |
+| `UpdateReportGroup` | Partial update by ARN |
+| `DeleteReportGroup` | Removes report group by ARN |
+| `BatchGetReportGroups` | Returns found report groups and a `reportGroupsNotFound` list |
+| `ListReportGroups` | Returns all report group ARNs in the region |
+
+### Source Credentials
+
+| Operation | Notes |
+|---|---|
+| `ImportSourceCredentials` | Stores server type and auth type; deduplicated by `serverType+authType`; token is accepted but not returned |
+| `ListSourceCredentials` | Returns stored credential metadata (no tokens) |
+| `DeleteSourceCredentials` | Removes source credentials by ARN |
+
+### Images
+
+| Operation | Notes |
+|---|---|
+| `ListCuratedEnvironmentImages` | Returns a static list of standard CodeBuild images for AL2 and Ubuntu |
+
+## Build Execution Model
+
+Each `StartBuild` call:
+
+1. Pulls the project's Docker image (e.g. `public.ecr.aws/docker/library/alpine:latest`)
+2. Starts a container with the working directories pre-created
+3. Injects source files into the container via `docker cp` (`NO_SOURCE` builds skip this step)
+4. Executes buildspec phases sequentially inside the container via `docker exec`
+5. Streams phase output to CloudWatch Logs under `/aws/codebuild/<project>`
+6. Extracts artifact files from the container via `docker cp` and uploads them to S3 if `artifacts.type=S3`
+7. Marks the build complete with `SUCCEEDED`, `FAILED`, or `STOPPED`
+
+Source injection and artifact extraction both use the Docker API's archive copy endpoints — no bind mounts are required. This works correctly when Floci itself runs inside a Docker container (Docker-in-Docker).
+
+## Buildspec Support
+
+Floci parses the `buildspec.yml` embedded in the project or provided via `buildspecOverride`. Supported fields:
+
+- `phases` — `install`, `pre_build`, `build`, `post_build` command lists
+- `artifacts.files` — list of file patterns to collect; supports `**/*` glob, specific filenames, and path patterns
+- `artifacts.base-directory` — base directory for artifact collection (default: `$CODEBUILD_SRC_DIR`)
+
+## Artifact Upload
+
+When `artifacts.type=S3`, collected files are uploaded to the configured S3 bucket. The bucket must exist (created via `CreateBucket`). File paths in S3 match the relative path from the artifact base directory.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `FLOCI_SERVICES_CODEBUILD_ENABLED` | `true` | Enable or disable the service |
+
+## CLI Examples
+
+```bash
+# Create a project with S3 artifacts
+aws --endpoint-url http://localhost:4566 codebuild create-project \
+  --name my-project \
+  --source type=NO_SOURCE \
+  --artifacts type=S3,location=my-bucket \
+  --environment type=LINUX_CONTAINER,image=public.ecr.aws/docker/library/alpine:latest,computeType=BUILD_GENERAL1_SMALL \
+  --service-role arn:aws:iam::000000000000:role/codebuild-role
+
+# Start a build with inline buildspec
+aws --endpoint-url http://localhost:4566 codebuild start-build \
+  --project-name my-project \
+  --buildspec-override 'version: 0.2
+phases:
+  build:
+    commands:
+      - echo hello > output.txt
+artifacts:
+  files:
+    - output.txt'
+
+# Poll until complete
+aws --endpoint-url http://localhost:4566 codebuild batch-get-builds --ids <build-id>
+
+# List all builds
+aws --endpoint-url http://localhost:4566 codebuild list-builds
+
+# List curated images
+aws --endpoint-url http://localhost:4566 codebuild list-curated-environment-images
+```