AWS CodeDeploy ExecModule

Overview

AwsCodeDeployModule brings bounded AWS CodeDeploy discovery, deployment-group and configuration inspection, rollout and target status, and exact deployment controls into ValkyrAI workflows. Release, incident, and platform workflows can reconcile the application and deployment group they intend to affect, inspect recent rollouts and target health, launch one reviewed immutable S3 revision, or stop one exact deployment without accepting arbitrary scripts, inline AppSpec content, IAM roles, target selectors, alarm overrides, or lifecycle-hook decisions.

The connector implements twelve operations:

• list_applications and get_application discover applications and read one exact application.
• list_deployment_groups and get_deployment_group discover groups and inspect their configured deployment policy and last rollout references.
• list_deployments and get_deployment inspect bounded rollout history and one exact deployment.
• list_deployment_configs and get_deployment_config inspect available rollout configurations and minimum healthy-host policy.
• list_deployment_targets and get_deployment_target inspect target identifiers and safe target status across EC2/on-premises, Lambda, ECS, and CloudFormation deployments.
• create_deployment launches one exact reviewed S3 revision after explicit confirmation.
• stop_deployment stops one exact deployment, with an explicit rollback choice, after confirmation.

n8n's reusable AWS credential and resource/operation/action node pattern is the functional workflow reference. ValkyrAI follows its native IntegrationAccount contract and adds operation-specific allowlists, strict identifier and revision validation, bounded pagination, raw-credential rejection, confidential normalized output, read-only retries, and single-attempt deployment mutations.

Usage

1. Identify the AWS account, region, application, deployment group, and deployment configuration the workflow may use.
2. Create a least-privilege AWS principal with only the CodeDeploy read or deployment-control actions the workflow requires.
3. Store the access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsCodeDeployModule and bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Use application, group, and configuration reads to reconcile the exact target before approving a deployment.
6. For a launch, provide an immutable S3 bucket/key plus an object version and/or ETag whenever the bucket supports them.
7. Set confirmCreateDeployment: true only after the revision, group, and rollout policy have been reviewed.
8. Persist the returned deployment ID and AWS request ID, then use get_deployment and target reads until the rollout reaches a terminal state.
9. Set confirmStopDeployment: true only after reconciling that exact deployment and choosing whether updated targets should roll back.

Never put access keys, secret keys, session tokens, credential objects, inline AppSpec bodies, GitHub tokens, lifecycle-hook payloads, IAM roles, target filters, alarm overrides, or arbitrary provider request fields in module input. Raw credential-shaped fields and every undocumented override fail before network access. Application, group, configuration, deployment, target, revision, timing, and health details are confidential workflow data.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the twelve 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 result bound from 1 through 1,000.
returnAll	boolean	List operations	false	Follow pages until limit, provider exhaustion, or 100 pages.
applicationName	string	Application/group reads and create	None	Exact 1-100 character CodeDeploy name.
deploymentGroupName	string	Exact group read and create	None	Exact 1-100 character CodeDeploy name.
deploymentId	string	Deployment/target reads and stop	None	Exact bounded provider deployment ID.
targetId	string	get_deployment_target	None	Exact bounded provider target ID or ARN.
deploymentConfigName	string	Exact config read; optional create	Group default	Exact 1-100 character configuration name.
statusFilters	array or comma-separated string	Optional list_deployments field	All	created, queued, in_progress, baking, succeeded, failed, stopped, or ready.
s3Bucket	string	create_deployment	None	Valid 3-63 character S3 bucket name.
s3Key	string	create_deployment	None	Non-empty object key, at most 1,024 characters.
s3BundleType	string	create_deployment	zip	zip, tar, tgz, yaml, or json; support depends on compute platform.
s3Version	string	Optional create field	Latest matching object	Exact S3 object version, at most 1,024 characters.
s3ETag	string	Optional create field	None	Exact S3 object ETag, at most 1,024 characters.
description	string	Optional create field	None	Non-secret release description, at most 256 characters.
autoRollbackEnabled	boolean	Optional stop field	false	Roll back targets already updated by the stopped deployment.
confirmCreateDeployment	boolean	create_deployment	false	Must be exactly true.
confirmStopDeployment	boolean	stop_deployment	false	Must be exactly true.

For list_deployments, applicationName and deploymentGroupName must either both be present or both be omitted. Unexpected fields fail before provider access. This prevents hidden revision types, role changes, instance selectors, inline content, alarm bypasses, lifecycle overrides, and deployment-group mutation.

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	Application, group, deployment, config, target, or control family.
items	array	List success	Bounded normalized names or identifiers.
count	integer	List success	Number of returned items.
pages	integer	List success	Provider pages consumed.
hasMore	boolean	List success	Whether AWS returned another token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Exact read or control success	Normalized resource details or mutation receipt.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Application output includes bounded identity, compute platform, creation time, and GitHub-link state, but not stored GitHub account names. Deployment-group output includes identity, configuration, compute platform, outdated-instance strategy, and last attempted/successful deployment references, but not service-role ARNs, target rules, trigger destinations, load balancer identities, or alarm names.

Deployment output includes exact identity, state, compute platform, timing, target counts, file behavior, and a bounded S3 revision locator. It omits provider diagnostics, lifecycle payloads, arbitrary status messages, IAM identities, alarm details, and rollback internals. Target output includes exact identity, type, status, and update time; it omits lifecycle event diagnostics and provider messages.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / CodeDeploy
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:

• Application discovery: codedeploy:ListApplications and codedeploy:GetApplication.
• Group discovery: codedeploy:ListDeploymentGroups and codedeploy:GetDeploymentGroup.
• Deployment and target state: codedeploy:ListDeployments, codedeploy:GetDeployment, codedeploy:ListDeploymentTargets, and codedeploy:GetDeploymentTarget.
• Configuration discovery: codedeploy:ListDeploymentConfigs and codedeploy:GetDeploymentConfig.
• Controls: codedeploy:CreateDeployment and/or codedeploy:StopDeployment only for explicitly governed applications and groups.

Use application/deployment-group resource constraints, AWS resource tags, permissions boundaries, organization service-control policies, separate read/control accounts, and immutable S3 artifact policy to reduce blast radius. Prefer a read-only account unless launch or stop control is an explicit workflow requirement. CreateDeployment may also require S3 read and KMS decrypt permissions for the selected artifact through the identities CodeDeploy uses.

Configuration

The awsAccount relationship is the only credential configuration. Operation, exact resource identity, pagination, status filters, S3 revision locator, rollback choice, and confirmations belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-codedeploy-release"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"create_deployment\",\"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_applications	Lists bounded application names.	Read-only; each page retries transient failures.
get_application	Reads one exact application identity and compute platform.	Read-only; bounded retry.
list_deployment_groups	Lists bounded group names for one application.	Read-only; each page retries transient failures.
get_deployment_group	Reads safe rollout policy and last-deployment references.	Read-only; bounded retry.
list_deployments	Lists bounded deployment IDs, optionally filtered by exact application/group and statuses.	Read-only; each page retries transient failures.
get_deployment	Reads one exact rollout, revision locator, timing, and target overview.	Read-only; bounded retry.
list_deployment_configs	Lists bounded configuration names.	Read-only; each page retries transient failures.
get_deployment_config	Reads one exact config's compute platform and minimum healthy-host policy.	Read-only; bounded retry.
list_deployment_targets	Lists bounded target IDs for one deployment.	Read-only; each page retries transient failures.
get_deployment_target	Reads safe status for one exact target.	Read-only; bounded retry.
create_deployment	Deploys one reviewed S3 revision through an exact application/group.	Confirmed external mutation; exactly one attempt.
stop_deployment	Attempts to stop one exact deployment, optionally rolling back updated targets.	Confirmed destructive mutation; exactly one attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, resource, status, S3 revision, bound, or confirmation; paired list filter missing; or 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_CODEDEPLOY_HTTP_400	Resource absent, invalid revision/configuration/state, deployment already terminal, or unsupported compute-platform combination.	Usually no	Read the exact application, group, deployment, and configuration before deciding.
AWS_CODEDEPLOY_HTTP_403	IAM, SCP, S3, KMS, role, tag, or resource policy denied the request.	No	Grant only the missing action or revise the governed workflow.
AWS_CODEDEPLOY_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; writes remain single-attempt	Reconcile deployment state before mutation replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; writes report ambiguity	Treat mutation acceptance as unknown until 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, revision details, deployment topology, instance identity, IAM data, lifecycle diagnostics, and provider state from leaking through failures.

Example

Launch one reviewed immutable S3 revision:

{
  "operation": "create_deployment",
  "region": "us-west-2",
  "applicationName": "valkyrai",
  "deploymentGroupName": "production",
  "deploymentConfigName": "CodeDeployDefault.HalfAtATime",
  "s3Bucket": "reviewed-artifacts",
  "s3Key": "valkyrai/1.2.3.zip",
  "s3BundleType": "zip",
  "s3Version": "3Lg...immutable-version",
  "s3ETag": "reviewed-object-etag",
  "description": "Reviewed ValkyrAI 1.2.3 release",
  "confirmCreateDeployment": true
}

Expected result shape:

{
  "status": "success",
  "operation": "create_deployment",
  "attempts": 1,
  "resultType": "deployment_control",
  "data": {
    "accepted": true,
    "action": "create",
    "deploymentId": "d-provider-reference"
  },
  "requestId": "aws-request-reference"
}

Use the returned exact deployment ID with get_deployment, then list and inspect targets until the rollout reaches Succeeded, Failed, or Stopped. A successful create response proves provider acceptance, not application health or rollout completion.

Notes

• Pagination: list operations accept an opaque nextToken; all loops stop at limit, provider exhaustion, or 100 pages. CodeDeploy controls page size, so the connector enforces a total bound rather than requesting an arbitrary page size.
• 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. CodeDeploy CreateDeployment and StopDeployment do not accept caller idempotency tokens here, so ValkyrAI issues each mutation once. Preserve the exact inputs and reconcile deployment state before any manual replay.
• Revision integrity: s3Version and s3ETag are optional because provider and bucket configurations differ, but production workflows should pin every immutable identifier available. Omitting both can allow a mutable key to resolve differently later.
• Destructive behavior: stopping EC2/on-premises rollouts can leave targets in mixed states. autoRollbackEnabled: true requests rollback for updated targets but does not guarantee rollback success. Inspect the deployment and every relevant target afterward.
• Compute platforms: S3 bundle formats and deployment configuration compatibility vary across EC2/on-premises, Lambda, ECS, and CloudFormation. The module validates bounded syntax; CodeDeploy remains authoritative for platform compatibility.
• Status filters: list_deployments returns IDs only. Use get_deployment for authoritative status, revision, timing, and target counts.
• Secret safety: the module does not accept inline AppSpec content, GitHub revisions, arbitrary strings, lifecycle event decisions, instance selectors, IAM roles, alarm overrides, target-group details, or raw provider requests.
• Deferred scope: application/group/config create-update-delete, revision registration, GitHub token handling, lifecycle-hook acknowledgements, wait-time skipping, continuation, rollback overrides, alarm overrides, and on-premises instance registration 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 plus reviewed application, group, configuration, and artifact scope.