AWS CodeBuild ExecModule

Overview

AwsCodeBuildModule brings bounded AWS CodeBuild project discovery, build-history inspection, build-detail reads, and exact run controls into ValkyrAI workflows. Release, incident, and platform workflows can identify a project, inspect current or historical build state, start a reviewed revision, stop one exact running build, or retry a known build without accepting arbitrary buildspec or environment-variable overrides.

The connector implements eight operations:

• list_projects and batch_get_projects discover project identity and safe configuration summaries.
• list_builds, list_builds_for_project, and batch_get_builds retrieve bounded build identifiers and normalized build state.
• start_build starts one exact project, optionally at a reviewed source revision and with a provider idempotency token.
• stop_build attempts to stop one exact build after explicit confirmation.
• retry_build restarts one exact build after explicit confirmation and may use a provider idempotency token.

n8n's reusable AWS credential model is the functional workflow reference: region and AWS identity belong in a reusable credential rather than ordinary node input. ValkyrAI follows its native IntegrationAccount contract and adds operation-specific field allowlists, project/build identity validation, bounded pagination, raw-credential rejection, read-only retries, single-attempt mutations, confidential output classification, and deterministic receipts.

Usage

1. Identify the AWS account, region, CodeBuild projects, and build controls a workflow may use.
2. Create a least-privilege AWS principal with only the required CodeBuild actions and project resource conditions.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsCodeBuildModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Use list_projects and batch_get_projects to reconcile the exact project before accepting a project name from another workflow step.
6. Use list_builds_for_project followed by batch_get_builds to inspect current status and retain the AWS request ID.
7. Require a reviewed source revision and an explicit confirmation before start_build.
8. Read the exact build immediately before and after stop_build or retry_build so ambiguous outcomes are reconciled instead of blindly replayed.

Never put access keys, secret keys, session tokens, credential objects, buildspec text, registry credentials, certificates, or environment-variable overrides in module input. Raw credential-shaped fields and every undocumented override fail before network access. Treat project source locations, IAM roles, artifact locations, commit identifiers, build initiators, logs, and failure state as confidential workflow data.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the eight documented operations.
region	string	Every execution	None	Valid AWS region such as us-west-2.
nextToken	string	Optional list field	None	Opaque provider token, at most 4,096 characters.
limit	integer	List operations	100	Total bound from 1 through 1,000.
returnAll	boolean	List operations	false	Follow pages until limit, provider exhaustion, or 100 pages.
sortBy	string	list_projects	NAME	NAME, CREATED_TIME, or LAST_MODIFIED_TIME.
sortOrder	string	List operations	DESCENDING	ASCENDING or DESCENDING.
projectName	string	Project-scoped list/start or singular batch read	None	Exact 2-255 character CodeBuild project name.
projectNames	array	batch_get_projects	None	One through 100 distinct exact project names.
buildId	string	Stop/retry or singular batch read	None	Exact CodeBuild build ID, at most 512 characters.
buildIds	array	batch_get_builds	None	One through 100 distinct exact build IDs.
sourceVersion	string	Optional start_build field	Project default	Reviewed source revision, at most 512 characters.
idempotencyToken	string	Optional start/retry field	None	Up to 64 letters, digits, ., _, or -; retain it for reconciliation.
confirmStartBuild	boolean	start_build	false	Must be exactly true.
confirmStopBuild	boolean	stop_build	false	Must be exactly true.
confirmRetryBuild	boolean	retry_build	false	Must be exactly true.

projectName and projectNames are mutually exclusive. buildId and buildIds are mutually exclusive. Batch reads remove duplicate identifiers while preserving caller order. Unexpected fields fail before provider access, which deliberately prevents hidden buildspec, artifact, cache, compute, environment-variable, service-role, certificate, registry-credential, and privileged-mode overrides.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	Project name, project, build ID, build, or build-control family.
items	array	List or batch-read success	Bounded normalized project or build results.
count	integer	Items present	Number of returned items.
pages	integer	Paginated success	Provider pages consumed.
hasMore	boolean	Paginated success	Whether AWS returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Batch or run-control success	Not-found identifiers or normalized mutation receipt.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Project summaries include bounded identity, description, role, source, buildspec path, environment image/compute type, artifact configuration, timeouts, timestamps, encryption key, concurrency limit, and badge state. Environment-variable values, registry credentials, source authorization, certificate material, and webhook secrets are omitted.

Build summaries include identity, project, status, phase, source revisions, initiator, timestamps, completion, safe artifact checksums/location, log links, and bounded phase timing. They omit environment variables, source credentials, debug-session details, exported variables, provider error messages, and arbitrary build output.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / CodeBuild
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only actions used by the reviewed workflow:

• Project discovery: codebuild:ListProjects and codebuild:BatchGetProjects.
• Build reads: codebuild:ListBuilds, codebuild:ListBuildsForProject, and codebuild:BatchGetBuilds.
• Run controls: codebuild:StartBuild, codebuild:StopBuild, and/or codebuild:RetryBuild only for explicitly governed projects.

Use IAM project ARNs, resource tags, permissions boundaries, organization service-control policies, and separate read/run accounts to reduce blast radius. Prefer a read-only account unless build control is an explicit requirement. Starting a build also exercises the CodeBuild project's service role; reviewing the caller policy alone does not establish the build's downstream permissions.

Configuration

The awsAccount relationship is the only credential configuration. Operation, project/build identity, pagination, source revision, idempotency token, and safety confirmations belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-codebuild-release"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"start_build\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_projects	Lists bounded project names with selected sort order.	Read-only; each page retries transient failures.
batch_get_projects	Reads safe summaries for up to 100 exact project names and reports names not found.	Read-only; bounded retry.
list_builds	Lists bounded build IDs across the account/region.	Read-only; each page retries transient failures.
list_builds_for_project	Lists bounded build IDs for one exact project.	Read-only; each page retries transient failures.
batch_get_builds	Reads normalized details for up to 100 exact build IDs and reports IDs not found.	Read-only; bounded retry.
start_build	Starts one exact project, optionally at a reviewed source revision.	Confirmed external mutation; exactly one attempt.
stop_build	Attempts to stop one exact running build.	Confirmed destructive mutation; exactly one attempt.
retry_build	Restarts one exact build.	Confirmed external mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, project, build, list, bound, token, or confirmation; or an undocumented override.	No	Correct the named input; no AWS request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_CODEBUILD_HTTP_400	Invalid project/build, incompatible source revision, completed stop target, or provider input conflict.	Usually no	Inspect current project/build state and request ID.
AWS_CODEBUILD_HTTP_403	IAM, SCP, resource-tag, service-role, KMS, source, artifact, log, or VPC policy denied the request.	No	Grant only the missing action or revise the governed workflow.
AWS_CODEBUILD_HTTP_404	Exact project or build is absent.	No	Reconcile current region, project name, and build ID.
AWS_CODEBUILD_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; writes remain single-attempt	Reconcile project/build state before mutation replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; writes report ambiguity	Treat mutation acceptance as unknown until build state is read.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, project topology, source details, commit identifiers, artifact paths, IAM roles, and build state from leaking through failures.

Example

Start one reviewed release build:

{
  "operation": "start_build",
  "region": "us-west-2",
  "projectName": "valkyrai-release",
  "sourceVersion": "refs/heads/rc-7",
  "idempotencyToken": "release-20260908-1900",
  "confirmStartBuild": true
}

Expected result shape:

{
  "status": "success",
  "operation": "start_build",
  "attempts": 1,
  "resultType": "build_control",
  "data": {
    "accepted": true,
    "action": "start",
    "build": {
      "id": "valkyrai-release:provider-build-reference",
      "projectName": "valkyrai-release",
      "status": "IN_PROGRESS",
      "sourceVersion": "refs/heads/rc-7",
      "currentPhase": "SUBMITTED"
    }
  },
  "requestId": "aws-request-reference"
}

Use the returned exact build ID with batch_get_builds until the workflow reaches a terminal state. Do not treat a successful start response as proof that source checkout, commands, artifacts, reports, or deployment succeeded.

Notes

• Pagination: list operations accept an opaque nextToken; all loops stop at limit, provider exhaustion, or 100 pages. CodeBuild list APIs may return up to 100 identifiers per provider page.
• Batch limits: project and build detail reads accept at most 100 distinct identifiers. Not-found identifiers are returned separately from successful normalized items.
• Rate limits: AWS SDK internal retries are disabled. ValkyrAI applies bounded backoff only to read operations and honors ExecModule retry attempts from 1 through 5.
• Idempotency: reads are retry-safe. start_build and retry_build may carry a caller-owned provider idempotency token, but ValkyrAI still issues each mutation once. Preserve the same token during reconciliation; do not change inputs under a reused token.
• Destructive behavior: stop_build attempts to end one exact running build and can interrupt tests, artifacts, reports, and deployment steps. It requires confirmStopBuild: true; always inspect the exact build first.
• Secret safety: the module does not accept buildspec, environment-variable, compute, image, registry, certificate, cache, artifact, log, service-role, privileged-mode, or debug-session overrides. Manage those settings in the governed CodeBuild project.
• Build outcomes: start/retry acceptance is not build success. Follow the exact build ID and terminal status; use CloudWatch Logs, reports, artifacts, and deployment evidence through separately authorized workflows.
• Source versions: sourceVersion is passed to CodeBuild as a bounded opaque revision. Validate branch, tag, pull-request, or commit conventions in the approval workflow before confirmation.
• Deferred scope: project create/update/delete, webhooks, batch builds, report/test-case retrieval, caches, fleets, sandboxes, source credentials, resource policies, and arbitrary build overrides are intentionally excluded.
• External verification: repository tests use a deterministic transport and make no AWS call. Provider behavior requires a separately authorized least-privilege AWS account and reviewed project/build scope.