Manage Amazon CodeBuild builds with Step Functions - Amazon Step Functions
Supported APIsIAM policies
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Manage Amazon CodeBuild builds with Step Functions

You can integrate Step Functions with Amazon CodeBuild to start, stop, and manage builds. This page lists the supported CodeBuild APIs you can use with Step Functions.

To learn about integrating with Amazon services in Step Functions, see Integrating services and Passing parameters to a service API in Step Functions.

With the Step Functions integration with Amazon CodeBuild you can use Step Functions to trigger, stop, and manage builds, and to share build reports. Using Step Functions, you can design and run continuous integration pipelines for validating your software changes for applications.

Key features of Optimized CodeBuild integration

  • The Run a Job (.sync) integration pattern is supported.

  • After you call StopBuild or StopBuildBatch, the build or build batch is not immediately deletable until some internal work is completed within CodeBuild to finalize the state of the build or builds.

    If you attempt to use BatchDeleteBuilds or DeleteBuildBatch during this period, the build or build batch may not be deleted.

    The optimized service integrations for BatchDeleteBuilds and DeleteBuildBatch include an internal retry to simplify the use case of deleting immediately after stopping.

Not all APIs support all integration patterns, as shown in the following table.

API Request Response Run a Job (.sync)
StartBuild Supported Supported
StopBuild Supported Not supported
BatchDeleteBuilds Supported Not supported
BatchGetReports Supported Not supported
StartBuildBatch Supported Supported
StopBuildBatch Supported Not supported
RetryBuildBatch Supported Supported
DeleteBuildBatch Supported Not supported
Parameters in Step Functions are expressed in PascalCase

Even if the native service API is in camelCase, for example the API action startSyncExecution, you specify parameters in PascalCase, such as: StateMachineArn.

Optimized CodeBuild APIs

Note

When using JSONPath, you can use the recursive descent operator (..) to provide parameters for BatchDeleteBuilds. With the returned array, you can transform the Arn field from StartBuild into a plural Ids parameter, as shown in the following example.

"BatchDeleteBuilds": {
    "Type": "Task",
    "Resource": "arn:aws:states:::codebuild:batchDeleteBuilds",
    "Arguments": {
        "Ids.$": "$.Build..Arn"
    },
    "Next": "MyNextState"
},

IAM policies for calling Amazon CodeBuild

The following example templates show how Amazon Step Functions generates IAM policies based on the resources in your state machine definition. For more information, see How Step Functions generates IAM policies for integrated services and Discover service integration patterns in Step Functions.

Resources:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "sns:Publish"
            ],
            "Resource": [
                "arn:aws:sns:sa-east-1:account-id:StepFunctionsSample-CodeBuildExecution1111-2222-3333-wJalrXUtnFEMI-SNSTopic-bPxRfiCYEXAMPLEKEY"
            ],
            "Effect": "Allow"
        },
        {
            "Action": [
                "codebuild:StartBuild",
                "codebuild:StopBuild",
                "codebuild:BatchGetBuilds",
                "codebuild:BatchGetReports"
            ],
            "Resource": "*",
            "Effect": "Allow"
        },
        {
            "Action": [
                "events:PutTargets",
                "events:PutRule",
                "events:DescribeRule"
            ],
            "Resource": [
                "arn:aws:events:sa-east-1:account-id:rule/StepFunctionsGetEventForCodeBuildStartBuildRule"
            ],
            "Effect": "Allow"
        }
    ]
}

StartBuild

Static resources

Run a Job (.sync)
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:StartBuild",
        "codebuild:StopBuild",
        "codebuild:BatchGetBuilds"
      ],
      "Resource": [
        "arn:aws:codebuild:region:account-id:project/projectName"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "events:PutTargets",
        "events:PutRule",
        "events:DescribeRule"
      ],
      "Resource": [
        "arn:aws:events:region:account-id:rule/StepFunctionsGetEventForCodeBuildStartBuildRule"
      ]
    }
  ]
}
Request Response
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:StartBuild"
      ],
      "Resource": [
        "arn:aws:codebuild:region:account-id:project/projectName"
      ]
    }
  ]
}

Dynamic resources

Run a Job (.sync)
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:StartBuild",
        "codebuild:StopBuild",
        "codebuild:BatchGetBuilds"
      ],
      "Resource": [
        "arn:aws:codebuild:region:*:project/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "events:PutTargets",
        "events:PutRule",
        "events:DescribeRule"
      ],
      "Resource": [
        "arn:aws:events:region:account-id:rule/StepFunctionsGetEventForCodeBuildStartBuildRule"
      ]
    }
  ]
}
Request Response
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:StartBuild"
      ],
      "Resource": [
        "arn:aws:codebuild:region:*:project/*"
      ]
    }
  ]
}

StopBuild

Static resources

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:StopBuild"
      ],
      "Resource": [
        "arn:aws:codebuild:region:account-id:project/projectName"
      ]
    }
  ]
}

Dynamic resources

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:StopBuild"
      ],
      "Resource": [
        "arn:aws:codebuild:region:*:project/*"
      ]
    }
  ]
}

BatchDeleteBuilds

Static resources

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:BatchDeleteBuilds"
      ],
      "Resource": [
        "arn:aws:codebuild:region:account-id:project/projectName"
      ]
    }
  ]
}

Dynamic resources

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:BatchDeleteBuilds"
      ],
      "Resource": [
        "arn:aws:codebuild:region:*:project/*"
      ]
    }
  ]
}

BatchGetReports

Static resources

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:BatchGetReports"
      ],
      "Resource": [
        "arn:aws:codebuild:region:account-id:report-group/"
      ]
    }
  ]
}

Dynamic resources

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codebuild:BatchGetReports"
      ],
      "Resource": [
        "arn:aws:codebuild:region:*:report-group/*"
      ]
    }
  ]
}

StartBuildBatch

Static resources

Run a Job (.sync)
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:StartBuildBatch",
                "codebuild:StopBuildBatch",
                "codebuild:BatchGetBuildBatches"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/projectName"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "events:PutTargets",
                "events:PutRule",
                "events:DescribeRule"
            ],
            "Resource": [
                "arn:aws:events:region:account-id:rule/StepFunctionsGetEventForCodeBuildStartBuildBatchRule"
            ]
        }
    ]
}
Request Response
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:StartBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/projectName"
            ]
        }
    ]
}

Dynamic resources

Run a Job (.sync)
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:StartBuildBatch",
                "codebuild:StopBuildBatch",
                "codebuild:BatchGetBuildBatches"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/*"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "events:PutTargets",
                "events:PutRule",
                "events:DescribeRule"
            ],
            "Resource": [
                "arn:aws:events:region:account-id:rule/StepFunctionsGetEventForCodeBuildStartBuildBatchRule"
            ]
        }
    ]
}
Request Response
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:StartBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/*"
            ]
        }
    ]
}

StopBuildBatch

Static resources

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:StopBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/projectName"
            ]
        }
    ]
}

Dynamic resources

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:StopBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/*"
            ]
        }
    ]
}

RetryBuildBatch

Static resources

Run a Job (.sync)
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:RetryBuildBatch",
                "codebuild:StopBuildBatch",
                "codebuild:BatchGetBuildBatches"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/projectName"
            ]
        }
    ]
}
Request Response
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:RetryBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/projectName"
            ]
        }
    ]
}

Dynamic resources

Run a Job (.sync)
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:RetryBuildBatch",
                "codebuild:StopBuildBatch",
                "codebuild:BatchGetBuildBatches"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/*"
            ]
        }
    ]
}
Request Response
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:RetryBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/*"
            ]
        }
    ]
}

DeleteBuildBatch

Static resources

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:DeleteBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/projectName"
            ]
        }
    ]
}

Dynamic resources

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "codebuild:DeleteBuildBatch"
            ],
            "Resource": [
                "arn:aws:codebuild:region:account-id:project/*"
            ]
        }
    ]
}