Skip to content

Ministack: Free, open-source local AWS emulator - 60+ services, Terraform compatible, real databases. Free forever. MIT licensed.

CodeBuild: optionally execute builds via the official local agent (#1273)

Igor Gawryśb7261ed28c47
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7a45e655..319b5a64 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,11 @@ All notable changes to MiniStack will be documented here.
Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
Versioning follows [Semantic Versioning](https://semver.org/).
+## [Unreleased]
+
+### Added
+- **CodeBuild - builds can really run (`MINISTACK_CODEBUILD_EXECUTE=1`)** - `StartBuild` returned a build that was already `SUCCEEDED`, so a pipeline rehearsed against MiniStack reported a pass without a single phase having run, and a buildspec that fails on AWS still looked green locally. With the flag set, `StartBuild` returns `IN_PROGRESS` and the project's inline buildspec is handed to the official AWS CodeBuild local agent (`public.ecr.aws/codebuild/local-builds`), which runs the phases in the project's `environment.image` the way CodeBuild does - the phase semantics come from AWS's own agent instead of a reimplemented executor. `BatchGetBuilds` reflects progress while the build runs: the agent's `Phase complete: <PHASE> State: <STATUS>` lines become `phases` entries, and the container's exit status maps to `SUCCEEDED` / `FAILED`, with `FAULT` when Docker is unreachable. `environment.environmentVariables`, `privilegedMode`, and the `CODEBUILD_BUILD_ID` / `_ARN` / `_NUMBER` / `_INITIATOR` variables reach the build. The build reaches back into MiniStack: `AWS_ENDPOINT_URL` (plus placeholder credentials) is injected unless the project declares its own, so `aws s3 cp` inside a build hits this emulator rather than real AWS. `timeoutInMinutes` is enforced (the build is stopped and its phase reported `TIMED_OUT`), and a restored build that was in flight when MiniStack stopped is reported `FAULT` rather than polling as running forever. `StopBuild` is honoured deterministically: it records the intent before removing the container, so the worker reports the requested `STOPPED` instead of racing it to `FAULT`. Build output also reaches CloudWatch Logs: the record already advertised `logs.groupName` / `logs.streamName`, and an executed build now writes the agent output there, so `aws logs get-log-events` and `aws logs tail` read back a real build log instead of an empty stream. Default behaviour is unchanged - without the flag builds stay metadata-only. Requires the Docker socket; the agent image and workspace path are fixed internals, not configurable.
+
## [1.4.13] — 2026-08-06
### Fixed
diff --git a/README.md b/README.md
index 3278c23c..98b430cf 100644
--- a/README.md
+++ b/README.md
@@ -576,7 +576,7 @@ MiniStack expands AWS SAM transforms (`Transform: AWS::Serverless-2016-10-31`) i
| **RDS Data API** | ExecuteStatement, BatchExecuteStatement, BeginTransaction, CommitTransaction, RollbackTransaction | Routes SQL to real Docker-backed RDS database containers; supports MySQL (pymysql) and PostgreSQL (psycopg2); REST paths (`/Execute`, `/BeginTransaction`, etc.) |
| **S3 Files** | CreateFileSystem, GetFileSystem, ListFileSystems, DeleteFileSystem, CreateMountTarget, GetMountTarget, ListMountTargets, UpdateMountTarget, DeleteMountTarget, CreateAccessPoint, GetAccessPoint, ListAccessPoints, DeleteAccessPoint, GetFileSystemPolicy, PutFileSystemPolicy, DeleteFileSystemPolicy, GetSynchronizationConfiguration, PutSynchronizationConfiguration, TagResource, UntagResource, ListTagsForResource | 21 operations; control plane for the new S3 Files service (launched April 2026); file systems, mount targets, access points, policies |
| **AutoScaling** | CreateAutoScalingGroup, DescribeAutoScalingGroups, UpdateAutoScalingGroup, DeleteAutoScalingGroup, SetDesiredCapacity, DescribeAutoScalingInstances, CreateLaunchConfiguration, DescribeLaunchConfigurations, DeleteLaunchConfiguration, PutScalingPolicy, DescribePolicies, DeletePolicy, PutLifecycleHook, DescribeLifecycleHooks, DeleteLifecycleHook, CompleteLifecycleAction, RecordLifecycleActionHeartbeat, PutScheduledUpdateGroupAction, DescribeScheduledActions, DeleteScheduledAction, CreateOrUpdateTags, DescribeTags, DeleteTags | 24 actions; in-memory state — no real instances, but groups report `DesiredCapacity` in-service instances so Terraform's `aws_autoscaling_group` capacity waiter converges; full ASG lifecycle (launch configs, scaling policies, lifecycle hooks, scheduled actions, tags); CDK/Terraform compatible |
-| **CodeBuild** | CreateProject, BatchGetProjects, ListProjects, UpdateProject, DeleteProject, StartBuild, BatchGetBuilds, StopBuild, ListBuilds, ListBuildsForProject, BatchDeleteBuilds | 11 actions; builds complete immediately with SUCCEEDED status; project and build metadata stored in-memory |
+| **CodeBuild** | CreateProject, BatchGetProjects, ListProjects, UpdateProject, DeleteProject, StartBuild, BatchGetBuilds, StopBuild, ListBuilds, ListBuildsForProject, BatchDeleteBuilds | 11 actions; project and build metadata stored in-memory; builds complete immediately with SUCCEEDED status by default. Set `MINISTACK_CODEBUILD_EXECUTE=1` and mount the Docker socket to **really run them**: the project's inline buildspec goes to the official AWS CodeBuild local agent, which runs the phases in `environment.image`, and `BatchGetBuilds` reports live `phases` with a real `SUCCEEDED`/`FAILED` outcome. Execution needs the workspace shared with the host at the **same path** (`-v /tmp/ministack-codebuild:/tmp/ministack-codebuild`), because the agent bind-mounts it into the build container; a build gets `AWS_ENDPOINT_URL` pointing back at MiniStack, honours `timeoutInMinutes`, and is stopped by `StopBuild`. An executed build streams the agent output into its `logs.groupName` / `logs.streamName`, so `aws logs tail` reads the build log back |
| **AppConfig** | CreateApplication, GetApplication, ListApplications, UpdateApplication, DeleteApplication, CreateEnvironment, GetEnvironment, ListEnvironments, UpdateEnvironment, DeleteEnvironment, CreateConfigurationProfile, GetConfigurationProfile, ListConfigurationProfiles, UpdateConfigurationProfile, DeleteConfigurationProfile, CreateHostedConfigurationVersion, GetHostedConfigurationVersion, ListHostedConfigurationVersions, DeleteHostedConfigurationVersion, CreateDeploymentStrategy, GetDeploymentStrategy, ListDeploymentStrategies, UpdateDeploymentStrategy, DeleteDeploymentStrategy, StartDeployment, GetDeployment, ListDeployments, StopDeployment, TagResource, UntagResource, ListTagsForResource, StartConfigurationSession, GetLatestConfiguration | 33 operations; control plane + data plane; hosted configuration versions; deployments complete immediately; session-based configuration retrieval with token rotation |
| **Transfer Family** | CreateServer, DescribeServer, DeleteServer, ListServers, StartServer, StopServer, CreateUser, DescribeUser, DeleteUser, ListUsers, ImportSshPublicKey, DeleteSshPublicKey | 12 operations; **real SFTP listener** on `:2222` (override with `SFTP_PORT`) backed by S3 — `ls`, `put`, `get`, `mkdir`, `rename` work end-to-end against the local S3 emulator; `SFTP_PORT_PER_SERVER=1` allocates one port per `CreateServer` from `SFTP_BASE_PORT` (default 2300); SSH key auth scans every user across every server and account; `LOGICAL` and `PATH` home-directory mappings; host key persists across restarts when `PERSIST_STATE=1` |
| **IoT Core** | CreateThing, DescribeThing, ListThings, UpdateThing, DeleteThing, CreateThingType, CreateThingGroup, AddThingToThingGroup, ListThingsInThingGroup, CreateKeysAndCertificate, RegisterCertificate, UpdateCertificate, DeleteCertificate, AttachThingPrincipal, DetachThingPrincipal, ListThingPrincipals, ListPrincipalThings, CreatePolicy, CreatePolicyVersion, AttachPolicy, DetachPolicy, ListAttachedPolicies, ListTargetsForPolicy, DescribeEndpoint, Publish (HTTP), MQTT-over-WebSocket pub/sub | 24 operations + **real MQTT 3.1.1 over WebSocket** on the gateway port — clients use the address returned by `DescribeEndpoint`; local CA signs `CreateKeysAndCertificate` certificates (CA persists across restarts when `PERSIST_STATE=1`); multi-tenancy via transparent topic prefixing (same pattern as Transfer Family's shared SFTP listener); no plain TCP 1883 (real AWS IoT requires TLS or SigV4 on every connection); local CA cert available at `GET /_ministack/iot/ca.pem` for SDK trust configuration; IoT policies are stored but **not enforced** on the data plane |
diff --git a/ministack/services/codebuild.py b/ministack/services/codebuild.py
index 83fddb97..36826a20 100644
--- a/ministack/services/codebuild.py
+++ b/ministack/services/codebuild.py
@@ -7,12 +7,18 @@ Supports:
UpdateProject, DeleteProject
Builds: StartBuild, BatchGetBuilds, StopBuild,
ListBuilds, ListBuildsForProject, BatchDeleteBuilds
+
+Builds are metadata-only by default. Set MINISTACK_CODEBUILD_EXECUTE=1 to
+really run them (see "Build execution" below).
"""
+import contextvars
import copy
import json
import logging
import os
+import re
+import threading
import time
from ministack.core.arn import ArnParseError, is_arn, parse_arn
@@ -40,6 +46,8 @@ _builds = AccountRegionScopedDict() # build_id -> build record
def reset():
_projects.clear()
_builds.clear()
+ with _stopped_lock:
+ _stopped_builds.clear()
def get_state():
@@ -53,6 +61,15 @@ def restore_state(data):
_projects.update(data.get("projects", {}))
_builds.update(data.get("builds", {}))
+ # An executed build lives in a container and a worker thread, neither of
+ # which survives a restart, so a restored IN_PROGRESS build would poll as
+ # running forever.
+ for build in _builds.values():
+ if build.get("buildStatus") == "IN_PROGRESS":
+ build["buildStatus"] = "FAULT"
+ build["currentPhase"] = "COMPLETED"
+ build.setdefault("endTime", int(time.time()))
+
try:
_restored = load_state("codebuild")
@@ -112,7 +129,8 @@ def _make_build_record(project, build_id, source_version=None):
return {
"id": build_id,
"arn": _build_arn(build_id),
- "buildNumber": len([b for b in _builds.values() if b["projectName"] == project["name"]]) + 1,
+ "buildNumber": len([b for b in _builds.values()
+ if b.get("projectName") == project["name"]]) + 1,
"startTime": now,
"endTime": now,
"currentPhase": "COMPLETED",
@@ -144,6 +162,325 @@ def _make_build_record(project, build_id, source_version=None):
}
+# ---------------------------------------------------------------------------
+# Build execution (opt-in via MINISTACK_CODEBUILD_EXECUTE=1)
+#
+# The buildspec is handed to the official AWS CodeBuild local agent, which runs
+# the phases in the project's image the way CodeBuild does, instead of this
+# emulator reimplementing an executor.
+#
+# WORKSPACE must resolve to the same path on the host and in this container,
+# because the agent bind-mounts it into the build container:
+# docker run -p 4566:4566 \
+# -v /var/run/docker.sock:/var/run/docker.sock \
+# -v /tmp/ministack-codebuild:/tmp/ministack-codebuild \
+# -e MINISTACK_CODEBUILD_EXECUTE=1 ministackorg/ministack
+# ---------------------------------------------------------------------------
+
+EXECUTE_BUILDS = os.environ.get("MINISTACK_CODEBUILD_EXECUTE", "0").lower() in ("1", "true", "yes")
+
+# The fixed image AWS's own codebuild_build.sh uses to run a local build; not
+# a real choice, so it is not configurable.
+AGENT_IMAGE = "public.ecr.aws/codebuild/local-builds:latest"
+
+# Internal scratch space for the source/artifacts/env files handed to the
+# agent container; not an AWS concept, so not configurable.
+WORKSPACE = "/tmp/ministack-codebuild"
+
+_PHASE_COMPLETE_RE = re.compile(r"Phase complete: ([A-Z_]+) State: ([A-Z_]+)")
+
+_docker = None
+
+# StopBuild removes the container, which ends the worker's log stream; without
+# recording the intent the worker would overwrite the requested STOPPED outcome
+# with FAULT or FAILED.
+_stopped_builds = set()
+_stopped_lock = threading.Lock()
+
+
+def _mark_stopped(build_id):
+ with _stopped_lock:
+ _stopped_builds.add(build_id)
+
+
+def _stop_requested(build_id):
+ with _stopped_lock:
+ return build_id in _stopped_builds
+
+
+def _clear_stopped(build_id):
+ with _stopped_lock:
+ _stopped_builds.discard(build_id)
+
+
+def _get_docker():
+ global _docker
+ if _docker is None:
+ try:
+ import docker
+ _docker = docker.from_env()
+ except Exception:
+ logger.exception("Docker unavailable; builds stay metadata-only")
+ _docker = False
+ return _docker or None
+
+
+def _log_sink(build):
+ """Return a callable that appends a line to the build's log stream.
+
+ The build record already advertises ``logs.groupName`` / ``logs.streamName``,
+ so an executed build writes its output there and `aws logs` reads it back.
+ """
+ from ministack.services import cloudwatch_logs as _cwl
+
+ group_name = build["logs"]["groupName"]
+ stream_name = build["logs"]["streamName"]
+ now_ms = int(time.time() * 1000)
+
+ if group_name not in _cwl._log_groups:
+ _cwl._log_groups[group_name] = {
+ "arn": _cwl._make_group_arn(group_name),
+ "creationTime": now_ms,
+ "retentionInDays": None,
+ "tags": {},
+ "subscriptionFilters": {},
+ "streams": {},
+ }
+ group = _cwl._log_groups[group_name]
+ if stream_name not in group["streams"]:
+ group["streams"][stream_name] = {
+ "events": [],
+ "uploadSequenceToken": "1",
+ "creationTime": now_ms,
+ "firstEventTimestamp": None,
+ "lastEventTimestamp": None,
+ "lastIngestionTime": None,
+ }
+ stream = group["streams"][stream_name]
+
+ def emit(line):
+ ts = int(time.time() * 1000)
+ events = stream["events"]
+ events.append({"timestamp": ts, "message": line, "ingestionTime": ts})
+ if stream["firstEventTimestamp"] is None:
+ stream["firstEventTimestamp"] = ts
+ stream["lastEventTimestamp"] = ts
+ stream["lastIngestionTime"] = ts
+
+ return emit
+
+
+def _container_for_build(build_id):
+ client = _get_docker()
+ if not client:
+ return None
+ found = client.containers.list(
+ all=True, filters={"label": f"ministack.codebuild.build={build_id}"}
+ )
+ return found[0] if found else None
+
+
+def _aws_endpoint():
+ """Address the build container can reach MiniStack on, or "" if it can't.
+
+ A build that calls the AWS CLI should reach this emulator rather than real
+ AWS. The build container is a sibling started by the agent, so it reaches
+ MiniStack over the default bridge gateway.
+ """
+ port = os.environ.get("GATEWAY_PORT") or os.environ.get("EDGE_PORT") or "4566"
+ client = _get_docker()
+ if not client:
+ return ""
+ try:
+ config = client.networks.get("bridge").attrs["IPAM"]["Config"]
+ gateway = next(entry["Gateway"] for entry in config if entry.get("Gateway"))
+ except Exception:
+ logger.debug("Could not resolve the bridge gateway; builds get no AWS endpoint")
+ return ""
+ return f"http://{gateway}:{port}"
+
+
+def _write_env_file(path, project, build):
+ env = project.get("environment", {}) or {}
+ declared = {var.get("name") for var in env.get("environmentVariables") or []}
+ with open(path, "w", encoding="utf-8") as fh:
+ for var in env.get("environmentVariables") or []:
+ fh.write(f"{var.get('name', '')}={var.get('value', '')}\n")
+ fh.write(f"CODEBUILD_BUILD_ID={build['id']}\n")
+ fh.write(f"CODEBUILD_BUILD_ARN={build['arn']}\n")
+ fh.write(f"CODEBUILD_BUILD_NUMBER={build['buildNumber']}\n")
+ fh.write(f"CODEBUILD_INITIATOR={build['initiator']}\n")
+ fh.write(f"AWS_DEFAULT_REGION={get_region()}\n")
+
+ endpoint = _aws_endpoint()
+ if endpoint and "AWS_ENDPOINT_URL" not in declared:
+ fh.write(f"AWS_ENDPOINT_URL={endpoint}\n")
+ for name, value in (("AWS_ACCESS_KEY_ID", "test"),
+ ("AWS_SECRET_ACCESS_KEY", "test")):
+ if name not in declared:
+ fh.write(f"{name}={value}\n")
+
+
+def _record_phase(build, phase_type, status):
+ now = int(time.time())
+ for phase in build["phases"]:
+ if phase["phaseType"] == phase_type and "endTime" not in phase:
+ phase["phaseStatus"] = status
+ phase["endTime"] = now
+ break
+ else:
+ build["phases"].append(
+ {"phaseType": phase_type, "phaseStatus": status, "startTime": now, "endTime": now}
+ )
+ build["currentPhase"] = phase_type
+
+
+def _finish_build(build, status):
+ build["buildStatus"] = status
+ build["currentPhase"] = "COMPLETED"
+ build["endTime"] = int(time.time())
+ _record_phase(build, "COMPLETED", status)
+
+
+def _timeout_seconds(project):
+ try:
+ minutes = int(project.get("timeoutInMinutes") or 60)
+ except (TypeError, ValueError):
+ minutes = 60
+ return max(1, minutes) * 60
+
+
+def _execute_build(build_id, project):
+ """Run a build through the CodeBuild local agent; update its record live."""
+ build = _builds.get(build_id)
+ client = _get_docker()
+ if build is None:
+ return
+ if not client:
+ _finish_build(build, "FAULT")
+ return
+
+ env = project.get("environment", {}) or {}
+ workdir = os.path.join(WORKSPACE, build_id.replace(":", "_"))
+ source_dir = os.path.join(workdir, "src")
+ artifacts_dir = os.path.join(workdir, "artifacts")
+ env_dir = os.path.join(workdir, "env")
+
+ try:
+ for path in (source_dir, artifacts_dir, env_dir):
+ os.makedirs(path, exist_ok=True)
+
+ buildspec = (project.get("source") or {}).get("buildspec") or ""
+ if not buildspec.strip():
+ logger.error("Build %s has no inline buildspec to execute", build_id)
+ _finish_build(build, "FAILED")
+ return
+
+ buildspec_path = os.path.join(source_dir, "buildspec.yml")
+ with open(buildspec_path, "w", encoding="utf-8") as fh:
+ fh.write(buildspec)
+ _write_env_file(os.path.join(env_dir, "env.list"), project, build)
+
+ _record_phase(build, "QUEUED", "SUCCEEDED")
+ build["buildStatus"] = "IN_PROGRESS"
+
+ container = client.containers.run(
+ AGENT_IMAGE,
+ detach=True,
+ environment={
+ "LOCAL_AGENT_IMAGE_NAME": AGENT_IMAGE,
+ "IMAGE_NAME": env.get("image", "aws/codebuild/standard:7.0"),
+ "SOURCE": source_dir,
+ "MOUNT_SOURCE_DIRECTORY": "TRUE",
+ "ARTIFACTS": artifacts_dir,
+ "BUILDSPEC": buildspec_path,
+ "ENV_VAR_FILE": "env.list",
+ "INITIATOR": "ministack",
+ "DOCKER_PRIVILEGED_MODE": "true" if env.get("privilegedMode") else "",
+ },
+ volumes={
+ "/var/run/docker.sock": {"bind": "/var/run/docker.sock", "mode": "rw"},
+ env_dir: {"bind": "/LocalBuild/envFile", "mode": "ro"},
+ },
+ labels={"ministack": "codebuild", "ministack.codebuild.build": build_id},
+ )
+ except Exception:
+ logger.exception("Failed to start build %s", build_id)
+ _finish_build(build, "FAULT")
+ return
+
+ try:
+ emit = _log_sink(build)
+ except Exception:
+ logger.exception("Could not open the log stream for %s", build_id)
+ emit = None
+
+ # The log stream blocks until the container ends, so the timeout is a timer
+ # that removes it; that ends the stream and is reported as TIMED_OUT.
+ timed_out = threading.Event()
+
+ def _on_timeout():
+ timed_out.set()
+ logger.error("Build %s exceeded timeoutInMinutes; stopping it", build_id)
+ try:
+ container.remove(force=True)
+ except Exception:
+ logger.exception("Could not stop the timed-out build %s", build_id)
+
+ timeout = threading.Timer(_timeout_seconds(project), _on_timeout)
+ timeout.daemon = True
+ timeout.start()
+
+ saw_phase = False
+ try:
+ for raw in container.logs(stream=True, follow=True):
+ if _stop_requested(build_id):
+ break
+ line = raw.decode("utf-8", "replace").rstrip()
+ if not line:
+ continue
+ logger.info("[%s] %s", build_id, line)
+ if emit is not None:
+ emit(line)
+ match = _PHASE_COMPLETE_RE.search(line)
+ if match:
+ saw_phase = True
+ _record_phase(build, match.group(1), match.group(2))
+
+ if _stop_requested(build_id):
+ logger.info("Build %s was stopped by request", build_id)
+ _finish_build(build, "STOPPED")
+ elif timed_out.is_set():
+ _record_phase(build, build.get("currentPhase") or "BUILD", "TIMED_OUT")
+ _finish_build(build, "FAILED")
+ else:
+ exit_code = container.wait().get("StatusCode", 1)
+ _finish_build(build, "SUCCEEDED" if exit_code == 0 else "FAILED")
+ logger.info("Build %s finished: %s", build_id, build["buildStatus"])
+ except Exception:
+ if _stop_requested(build_id):
+ logger.info("Build %s was stopped by request", build_id)
+ _finish_build(build, "STOPPED")
+ elif timed_out.is_set():
+ _record_phase(build, build.get("currentPhase") or "BUILD", "TIMED_OUT")
+ _finish_build(build, "FAILED")
+ else:
+ logger.exception("Build %s failed while running", build_id)
+ _finish_build(build, "FAULT")
+ finally:
+ timeout.cancel()
+ _clear_stopped(build_id)
+ if not saw_phase:
+ logger.warning(
+ "Build %s produced no 'Phase complete' lines; %s may not report "
+ "phases in this format", build_id, AGENT_IMAGE
+ )
+ try:
+ container.remove(force=True)
+ except Exception:
+ pass
+
+
# ---------------------------------------------------------------------------
# Request dispatcher
# ---------------------------------------------------------------------------
@@ -301,8 +638,30 @@ def _start_build(data):
project = _projects[project_name]
bid = _build_id(project_name)
build = _make_build_record(project, bid, data.get("sourceVersion"))
+
+ if EXECUTE_BUILDS:
+ now = build["startTime"]
+ build.pop("endTime", None)
+ build["buildStatus"] = "IN_PROGRESS"
+ build["currentPhase"] = "SUBMITTED"
+ build["phases"] = [
+ {"phaseType": "SUBMITTED", "phaseStatus": "SUCCEEDED", "startTime": now, "endTime": now},
+ {"phaseType": "QUEUED", "startTime": now},
+ ]
+
_builds[bid] = build
logger.info("StartBuild: %s -> %s", project_name, bid)
+
+ if EXECUTE_BUILDS:
+ # The stores are scoped by the request's account/region contextvars, so
+ # the worker has to run inside a copy of this request's context.
+ context = contextvars.copy_context()
+ threading.Thread(
+ target=context.run,
+ args=(_execute_build, bid, copy.deepcopy(project)),
+ daemon=True,
+ ).start()
+
return json_response({"build": copy.deepcopy(build)})
@@ -325,6 +684,16 @@ def _stop_build(data):
if not build:
return error_response_json("ResourceNotFoundException",
f"Build not found: {bid}", 400)
+ if EXECUTE_BUILDS:
+ _mark_stopped(bid)
+
+ container = _container_for_build(bid) if EXECUTE_BUILDS else None
+ if container:
+ try:
+ container.remove(force=True)
+ except Exception:
+ logger.exception("Could not stop the build container for %s", bid)
+
build["buildStatus"] = "STOPPED"
build["endTime"] = int(time.time())
build["currentPhase"] = "COMPLETED"
diff --git a/tests/test_codebuild.py b/tests/test_codebuild.py
index d5a374ff..44fc8fe4 100644
--- a/tests/test_codebuild.py
+++ b/tests/test_codebuild.py
@@ -1,10 +1,14 @@
+import json
import os
+import time
import boto3
import pytest
from botocore.config import Config
from botocore.exceptions import ClientError
+from ministack.services import codebuild
+
# ========== CodeBuild ==========
@@ -265,3 +269,308 @@ def test_codebuild_restore_legacy_state_uses_resource_arn_region():
) is None
finally:
service.reset()
+
+
+# ========== CodeBuild execution (MINISTACK_CODEBUILD_EXECUTE=1) ==========
+#
+# Execution hands the buildspec to the official CodeBuild local agent, so the
+# Docker client is faked here: these cover the build bookkeeping around the
+# agent (phase records, status mapping, the metadata-only default), not
+# Docker itself.
+
+
+class _FakeContainer:
+ def __init__(self, log_lines, exit_code=0):
+ self._log_lines = log_lines
+ self._exit_code = exit_code
+ self.removed = False
+
+ def logs(self, **_kwargs):
+ return iter(line.encode("utf-8") for line in self._log_lines)
+
+ def wait(self):
+ return {"StatusCode": self._exit_code}
+
+ def remove(self, **_kwargs):
+ self.removed = True
+
+
+class _FakeContainers:
+ def __init__(self, container):
+ self._container = container
+ self.image = None
+ self.kwargs = None
+
+ def run(self, image, **kwargs):
+ self.image = image
+ self.kwargs = kwargs
+ return self._container
+
+
+class _FakeDocker:
+ def __init__(self, container):
+ self.containers = _FakeContainers(container)
+
+
+EXECUTION_BUILDSPEC = "version: 0.2\nphases:\n build:\n commands:\n - echo hi\n"
+
+
+def _execution_project(buildspec=EXECUTION_BUILDSPEC):
+ return {
+ "name": "demo",
+ "arn": "arn:aws:codebuild:us-east-1:000000000000:project/demo",
+ "source": {"type": "NO_SOURCE", "buildspec": buildspec},
+ "artifacts": {"type": "NO_ARTIFACTS"},
+ "environment": {
+ "type": "LINUX_CONTAINER",
+ "image": "aws/codebuild/standard:7.0",
+ "computeType": "BUILD_GENERAL1_SMALL",
+ "privilegedMode": True,
+ "environmentVariables": [{"name": "FOO", "value": "bar"}],
+ },
+ "serviceRole": "arn:aws:iam::000000000000:role/codebuild-role",
+ }
+
+
+def _seed_execution_build(project, build_id="demo:0001"):
+ build = codebuild._make_build_record(project, build_id)
+ codebuild._builds[build_id] = build
+ return build
+
+
+def test_start_build_is_metadata_only_by_default(monkeypatch):
+ """Execution is opt-in: without the flag no container is ever created."""
+ calls = []
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: calls.append(1))
+ monkeypatch.setattr(codebuild, "EXECUTE_BUILDS", False)
+
+ project = _execution_project()
+ codebuild._projects["demo"] = project
+
+ status, _headers, body = codebuild._start_build({"projectName": "demo"})
+
+ assert status == 200
+ assert json.loads(body)["build"]["buildStatus"] == "SUCCEEDED"
+ assert calls == []
+
+
+def test_execute_build_records_phases_from_agent_log(monkeypatch, tmp_path):
+ container = _FakeContainer([
+ "Phase complete: INSTALL State: SUCCEEDED",
+ "[Container] running command echo hi",
+ "Phase complete: BUILD State: SUCCEEDED",
+ ])
+ docker = _FakeDocker(container)
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: docker)
+ monkeypatch.setattr(codebuild, "WORKSPACE", str(tmp_path))
+
+ project = _execution_project()
+ build = _seed_execution_build(project)
+
+ codebuild._execute_build("demo:0001", project)
+
+ assert build["buildStatus"] == "SUCCEEDED"
+ assert build["currentPhase"] == "COMPLETED"
+
+ phases = {p["phaseType"]: p.get("phaseStatus") for p in build["phases"]}
+ assert phases["INSTALL"] == "SUCCEEDED"
+ assert phases["BUILD"] == "SUCCEEDED"
+ assert phases["COMPLETED"] == "SUCCEEDED"
+ assert all("endTime" in p for p in build["phases"])
+
+ # The build runs in the project's image; the agent image only orchestrates.
+ assert docker.containers.image == codebuild.AGENT_IMAGE
+ assert docker.containers.kwargs["environment"]["IMAGE_NAME"] == "aws/codebuild/standard:7.0"
+ assert docker.containers.kwargs["environment"]["DOCKER_PRIVILEGED_MODE"] == "true"
+ assert container.removed is True
+
+ buildspec_path = docker.containers.kwargs["environment"]["BUILDSPEC"]
+ assert os.path.isfile(buildspec_path)
+ with open(buildspec_path, encoding="utf-8") as fh:
+ assert fh.read() == EXECUTION_BUILDSPEC
+
+ env_file = os.path.join(str(tmp_path), "demo_0001", "env", "env.list")
+ with open(env_file, encoding="utf-8") as fh:
+ env_lines = fh.read().splitlines()
+ assert "FOO=bar" in env_lines
+ assert "CODEBUILD_BUILD_ID=demo:0001" in env_lines
+
+
+def test_execute_build_writes_agent_output_to_cloudwatch_logs(monkeypatch, tmp_path):
+ from ministack.services import cloudwatch_logs as cwl
+
+ container = _FakeContainer([
+ "[Container] running command echo hi",
+ "Phase complete: BUILD State: SUCCEEDED",
+ ])
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: _FakeDocker(container))
+ monkeypatch.setattr(codebuild, "WORKSPACE", str(tmp_path))
+
+ project = _execution_project()
+ build = _seed_execution_build(project, "demo:0005")
+
+ codebuild._execute_build("demo:0005", project)
+
+ group = cwl._log_groups[build["logs"]["groupName"]]
+ stream = group["streams"][build["logs"]["streamName"]]
+ messages = [event["message"] for event in stream["events"]]
+
+ assert "[Container] running command echo hi" in messages
+ assert "Phase complete: BUILD State: SUCCEEDED" in messages
+ assert stream["firstEventTimestamp"] is not None
+ assert stream["lastEventTimestamp"] >= stream["firstEventTimestamp"]
+
+
+def test_execute_build_reports_failed_exit_code(monkeypatch, tmp_path):
+ container = _FakeContainer(["Phase complete: BUILD State: FAILED"], exit_code=1)
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: _FakeDocker(container))
+ monkeypatch.setattr(codebuild, "WORKSPACE", str(tmp_path))
+
+ project = _execution_project()
+ build = _seed_execution_build(project, "demo:0002")
+
+ codebuild._execute_build("demo:0002", project)
+
+ assert build["buildStatus"] == "FAILED"
+ phases = {p["phaseType"]: p.get("phaseStatus") for p in build["phases"]}
+ assert phases["BUILD"] == "FAILED"
+
+
+def test_execute_build_without_buildspec_never_starts_agent(monkeypatch, tmp_path):
+ docker = _FakeDocker(_FakeContainer([]))
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: docker)
+ monkeypatch.setattr(codebuild, "WORKSPACE", str(tmp_path))
+
+ project = _execution_project(buildspec="")
+ build = _seed_execution_build(project, "demo:0003")
+
+ codebuild._execute_build("demo:0003", project)
+
+ assert build["buildStatus"] == "FAILED"
+ assert docker.containers.image is None
+
+
+def test_execute_build_times_out_per_project_timeout(monkeypatch, tmp_path):
+ """A build past timeoutInMinutes is stopped and reported, not left running."""
+ class _HangingContainer(_FakeContainer):
+ def logs(self, **_kwargs):
+ # Ends only once the timeout fired and "removed" the container.
+ while not self.removed:
+ time.sleep(0.01)
+ return iter(())
+
+ container = _HangingContainer([])
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: _FakeDocker(container))
+ monkeypatch.setattr(codebuild, "WORKSPACE", str(tmp_path))
+ monkeypatch.setattr(codebuild, "_timeout_seconds", lambda _project: 0.2)
+
+ project = _execution_project()
+ build = _seed_execution_build(project, "demo:0006")
+
+ codebuild._execute_build("demo:0006", project)
+
+ assert build["buildStatus"] == "FAILED"
+ assert "TIMED_OUT" in [p.get("phaseStatus") for p in build["phases"]]
+
+
+def test_timeout_seconds_uses_the_project_value(monkeypatch):
+ assert codebuild._timeout_seconds({"timeoutInMinutes": 5}) == 300
+ assert codebuild._timeout_seconds({}) == 3600
+ assert codebuild._timeout_seconds({"timeoutInMinutes": "bogus"}) == 3600
+
+
+def test_env_file_points_the_build_at_ministack(monkeypatch, tmp_path):
+ """A build's AWS calls should reach this emulator, not real AWS."""
+ monkeypatch.setattr(codebuild, "_aws_endpoint", lambda: "http://172.17.0.1:4566")
+
+ project = _execution_project()
+ build = _seed_execution_build(project, "demo:0007")
+ env_file = tmp_path / "env.list"
+
+ codebuild._write_env_file(str(env_file), project, build)
+
+ lines = env_file.read_text(encoding="utf-8").splitlines()
+ assert "AWS_ENDPOINT_URL=http://172.17.0.1:4566" in lines
+ assert "AWS_ACCESS_KEY_ID=test" in lines
+
+
+def test_env_file_keeps_an_endpoint_the_project_declared(monkeypatch, tmp_path):
+ monkeypatch.setattr(codebuild, "_aws_endpoint", lambda: "http://172.17.0.1:4566")
+
+ project = _execution_project()
+ project["environment"]["environmentVariables"].append(
+ {"name": "AWS_ENDPOINT_URL", "value": "https://real.aws"}
+ )
+ build = _seed_execution_build(project, "demo:0008")
+ env_file = tmp_path / "env.list"
+
+ codebuild._write_env_file(str(env_file), project, build)
+
+ lines = env_file.read_text(encoding="utf-8").splitlines()
+ assert "AWS_ENDPOINT_URL=https://real.aws" in lines
+ assert "AWS_ENDPOINT_URL=http://172.17.0.1:4566" not in lines
+
+
+def test_restored_in_flight_builds_are_not_left_running():
+ """A build cannot survive a restart, so it must not restore as IN_PROGRESS."""
+ codebuild.restore_state({
+ "projects": {},
+ "builds": {"demo:0010": {
+ "id": "demo:0010",
+ "projectName": "demo",
+ "buildStatus": "IN_PROGRESS",
+ "currentPhase": "BUILD",
+ }},
+ })
+
+ restored = codebuild._builds["demo:0010"]
+ assert restored["buildStatus"] == "FAULT"
+ assert restored["currentPhase"] == "COMPLETED"
+ assert "endTime" in restored
+
+
+def test_stopped_build_is_not_overwritten_by_the_worker(monkeypatch, tmp_path):
+ """StopBuild removes the container, which is not a build failure.
+
+ Without this the worker's `container.wait()` raises on the removed container
+ and reports FAULT over the user's STOPPED.
+ """
+ class _RemovedContainer(_FakeContainer):
+ def logs(self, **_kwargs):
+ yield b"Phase complete: BUILD State: SUCCEEDED"
+ raise RuntimeError("container was removed")
+
+ def wait(self):
+ raise RuntimeError("container was removed")
+
+ container = _RemovedContainer([])
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: _FakeDocker(container))
+ monkeypatch.setattr(codebuild, "_container_for_build", lambda _bid: container)
+ monkeypatch.setattr(codebuild, "WORKSPACE", str(tmp_path))
+ monkeypatch.setattr(codebuild, "EXECUTE_BUILDS", True)
+
+ project = _execution_project()
+ codebuild._projects["demo"] = project
+ build = _seed_execution_build(project, "demo:0011")
+
+ codebuild._stop_build({"id": "demo:0011"})
+ assert build["buildStatus"] == "STOPPED"
+
+ codebuild._execute_build("demo:0011", project)
+
+ assert build["buildStatus"] == "STOPPED"
+ assert build["currentPhase"] == "COMPLETED"
+ # The registry must not leak once the worker is done.
+ assert codebuild._stop_requested("demo:0011") is False
+
+
+def test_execute_build_without_docker_reports_fault(monkeypatch, tmp_path):
+ monkeypatch.setattr(codebuild, "_get_docker", lambda: None)
+ monkeypatch.setattr(codebuild, "WORKSPACE", str(tmp_path))
+
+ project = _execution_project()
+ build = _seed_execution_build(project, "demo:0004")
+
+ codebuild._execute_build("demo:0004", project)
+
+ assert build["buildStatus"] == "FAULT"