Build and test actions YAML

The following is the YAML definition of the build and test actions. There is one reference for two actions because their YAML properties are very similar.

This action definition exists as a section within a broader workflow definition file. For more information about this file, see Workflow YAML definition.

Choose a YAML property in the following code to see a description if it.

Note

Most of the YAML properties that follow have corresponding UI elements in the visual editor. To look up a UI element, use Ctrl+F. The element will be listed with its associated YAML property.


# The workflow definition starts here.
# See Top-level properties for details.
        
Name: MyWorkflow
SchemaVersion: 1.0 
Actions:

# The action definition starts here.
  action-name:
    Identifier: aws/build@v1 | aws/managed-test@v1
    DependsOn:
      - dependent-action-name-1
    Compute:  
      Type: EC2 | Lambda
      Fleet: fleet-name
    Timeout: timeout-minutes
    Environment:
      Name: environment-name
      Connections:
        - Name: account-connection-name
          Role: iam-role-name
    Caching:  
      FileCaching:
        key-name-1:
          Path: file1.txt
          RestoreKeys:
            - restore-key-1
    Inputs:
      Sources:
        - source-name-1
        - source-name-2
      Artifacts:
        - artifact-name
      Variables:
        - Name: variable-name-1
          Value: variable-value-1
        - Name: variable-name-2
          Value: variable-value-2   
    Outputs:
      Artifacts:
        - Name: output-artifact-1
          Files: 
            - build-output/artifact-1.jar
            - "build-output/build*"
        - Name: output-artifact-2
          Files:
            - build-output/artifact-2.1.jar
            - build-output/artifact-2.2.jar
      Variables:
        - variable-name-1
        - variable-name-2
      AutoDiscoverReports:
        Enabled: true | false
        ReportNamePrefix: AutoDiscovered
        IncludePaths:
          - "**/*"
        ExcludePaths:
          - node_modules/cdk/junit.xml
        SuccessCriteria:
          PassRate: percent
          LineCoverage: percent
          BranchCoverage: percent
          Vulnerabilities:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisBug:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisSecurity:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisQuality:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
          StaticAnalysisFinding:
            Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
            Number: whole-number
      Reports:
        report-name-1:
          Format: format
          IncludePaths:
            - "*.xml"
          ExcludePaths:
            - report2.xml
            - report3.xml
          SuccessCriteria:
            PassRate: percent
            LineCoverage: percent
            BranchCoverage: percent
            Vulnerabilities:
              Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
              Number: whole-number
            StaticAnalysisBug:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
            StaticAnalysisSecurity:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
            StaticAnalysisQuality:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
            StaticAnalysisFinding:
                Severity: CRITICAL | HIGH | MEDIUM | LOW | INFORMATIONAL
                Number: whole-number
    Configuration:
      Container:
        Registry: registry
        Image: image
      Steps:
        - Run: "step 1"
        - Run: "step 2"
      Packages:
        NpmConfiguration:
          PackageRegistries:
            - PackagesRepository: package-repository
              Scopes:
                - "@scope"
        ExportAuthorizationToken: true | false

action-name

(Required)

Specify the name of the action. All action names must be unique within the workflow. Action names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (_). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in action names.

Corresponding UI: Configuration tab/Action name

Identifier

(action-name/Identifier)

Identifies the action. Do not change this property unless you want to change the version. For more information, see Specifying the action version to use.

Use aws/build@v1 for build actions.

Use aws/managed-test@v1 for test actions.

Corresponding UI: Workflow diagram/Action-name/aws/build@v1|aws/managed-test@v1 label

DependsOn

(action-name/DependsOn)

(Optional)

Specify an action, action group, or gate that must run successfully in order for this action to run.

For more information about the 'depends on' functionality, see Sequencing actions.

Corresponding UI: Inputs tab/Depends on - optional

Compute

(action-name/Compute)

(Optional)

The computing engine used to run your workflow actions. You can specify compute either at the workflow level or at the action level, but not both. When specified at the workflow level, the compute configuration applies to all actions defined in the workflow. At the workflow level, you can also run multiple actions on the same instance. For more information, see Sharing compute across actions.

Corresponding UI: none

Type

(action-name/Compute/Type)

(Required if Compute is included)

The type of compute engine. You can use one of the following values:

EC2 (visual editor) or EC2 (YAML editor)

Optimized for flexibility during action runs.
Lambda (visual editor) or Lambda (YAML editor)

Optimized action start-up speeds.

For more information about compute types, see Compute types.

Corresponding UI: Configuration tab/Compute type

Fleet

(action-name/Compute/Fleet)

(Optional)

Specify the machine or fleet that will run your workflow or workflow actions. With on-demand fleets, when an action starts, the workflow provisions the resources it needs, and the machines are destroyed when the action finishes. Examples of on-demand fleets: Linux.x86-64.Large, Linux.x86-64.XLarge. For more information about on-demand fleets, see On-demand fleet properties.

With provisioned fleets, you configure a set of dedicated machines to run your workflow actions. These machines remain idle, ready to process actions immediately. For more information about provisioned fleets, see Provisioned fleet properties.

If Fleet is omitted, the default is Linux.x86-64.Large.

Corresponding UI: Configuration tab/Compute fleet

Timeout

(action-name/Timeout)

(Optional)

Specify the amount of time in minutes (YAML editor), or hours and minutes (visual editor), that the action can run before CodeCatalyst ends the action. The minimum is 5 minutes and the maximum is described in Quotas for workflows in CodeCatalyst. The default timeout is the same as the maximum timeout.

Corresponding UI: Configuration tab/Timeout - optional

Environment

(action-name/Environment)

(Optional)

Specify the CodeCatalyst environment to use with the action. The action connects to the AWS account and optional Amazon VPC specified in the chosen environment. The action uses the default IAM role specified in the environment to connect to the AWS account, and uses the IAM role specified in the Amazon VPC connection to connect to the Amazon VPC.

Note

If the default IAM role does not have the permissions required by the action, you can configure the action to use a different role. For more information, see Changing the IAM role of an action.

For more information about environments, see Deploying into AWS accounts and VPCs and Creating an environment.

Corresponding UI: Configuration tab/Environment

Name

(action-name/Environment/Name)

(Optional)

Specify the name of an existing environment that you want to associate with the action.

Corresponding UI: Configuration tab/Environment

Connections

(action-name/Environment/Connections)

(Optional)

Specify the account connection to associate with the action. You can specify a maximum of one account connection under Environment.

If you do not specify an account connection:

The action uses the AWS account connection and default IAM role specified in the environment in the CodeCatalyst console. For information about adding an account connection and default IAM role to environment, see Creating an environment.
The default IAM role must include the policies and permissions required by the action. To determine what those policies and permissions are, see the description of the Role property in the action's YAML definition documentation.

For more information about account connections, see Allowing access to AWS resources with connected AWS accounts. For information about adding an account connection to an environment, see Creating an environment.

Corresponding UI: Configuration tab/Environment/What's in my-environment?/three dot menu/Switch role

Name

(action-name/Environment/Connections/Name)

(Required if Connections is included)

Specify the name of the account connection.

Corresponding UI: Configuration tab/Environment/What's in my-environment?/three dot menu/Switch role

Role

(action-name/Environment/Connections/Role)

(Required if Connections is included)

Specify the name of the IAM role that this action uses in order to access and operate in AWS services such as Amazon S3 and Amazon ECR. Make sure this role is added to your AWS account connection in your space. To add an IAM role to an account connection, see Adding IAM roles to account connections.

If you do not specify an IAM role, then the action uses the default IAM role listed in the environment in the CodeCatalyst console. If you use the default role in the environment, make sure it has the following policies.

Note

You can use the CodeCatalystWorkflowDevelopmentRole-spaceName role with this action. For more information about this role, see Creating the CodeCatalystWorkflowDevelopmentRole-spaceName role for your account and space. Understand that the CodeCatalystWorkflowDevelopmentRole-spaceName role has full access permissions which may pose a security risk. We recommend that you only use this role in tutorials and scenarios where security is less of a concern.

Warning

Limit the permissions to those required by the build and test actions. Using a role with broader permissions might pose a security risk.

Corresponding UI: Configuration tab/Environment/What's in my-environment?/three dot menu/Switch role

Caching

(action-name/Caching)

(Optional)

A section where you can specify a cache to save on-disk files and restore them from that cache in subsequent workflow runs.

For more information about file caching, see Caching files between workflow runs.

Corresponding UI: Configuration tab/File caching - optional

FileCaching

(action-name/Caching/FileCaching)

(Optional)

A section that specifies the configuration for a sequence of caches.

Corresponding UI: Configuration tab/File caching - optional/Add cache

key-name-1

(action-name/Caching/FileCaching/key-name-1)

(Optional)

Specify the name of your primary cache property name. Cache property names must be unique within your workflow. Each action can have up to five entries in FileCaching.

Corresponding UI: Configuration tab/File caching - optional/Add cache/Key

Path

(action-name/Caching/FileCaching/key-name-1/Path)

(Optional)

Specify the associated path for your cache.

Corresponding UI: Configuration tab/File caching - optional/Add cache/Path

RestoreKeys

(action-name/Caching/FileCaching/key-name-1/RestoreKeys)

(Optional)

Specify the restore key to use as a fallback when the primary cache property can't be found. Restore key names must be unique within your workflow. Each cache can have up to five entries in RestoreKeys.

Corresponding UI: Configuration tab/File caching - optional/Add cache/Restore keys - optional

Inputs

(action-name/Inputs)

(Optional)

The Inputs section defines the data that an action needs during a workflow run.

Note

A maximum of four inputs (one source and three artifacts) are allowed per build action or test action. Variables do not count towards this total.

If you need to refer to files residing in different inputs (say a source and an artifact), the source input is the primary input, and the artifact is the secondary input. References to files in secondary inputs take a special prefix to distiguish them from the primary. For details, see Example: Referencing files in multiple artifacts.

Corresponding UI: Inputs tab

Sources

(action-name/Inputs/Sources)

(Optional)

Specify the labels that represent the source repositories that will be needed by the action. Currently, the only supported label is WorkflowSource, which represents the source repository where your workflow definition file is stored.

If you omit a source, then you must specify at least one input artifact under action-name/Inputs/Artifacts.

For more information about sources, see Connecting source repositories to workflows.

Corresponding UI: none

Artifacts - input

(action-name/Inputs/Artifacts)

(Optional)

Specify artifacts from previous actions that you want to provide as input to this action. These artifacts must already be defined as output artifacts in previous actions.

If you do not specify any input artifacts, then you must specify at least one source repository under action-name/Inputs/Sources.

For more information about artifacts, including examples, see Sharing artifacts and files between actions.

Note

If the Artifacts - optional drop-down list is unavailable (visual editor), or if you get errors in when you validate your YAML (YAML editor), it might be because the action only supports one input. In this case, try removing the source input.

Corresponding UI: Inputs tab/Artifacts - optional

Variables - input

(action-name/Inputs/Variables)

(Optional)

Specify a sequence of name/value pairs that define the input variables that you want to make available to the action. Variable names are limited to alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and underscores (_). Spaces are not allowed. You cannot use quotation marks to enable special characters and spaces in variable names.

For more information about variables, including examples, see Using variables in workflows.

Corresponding UI: Inputs tab/Variables - optional

Outputs

(action-name/Outputs)

(Optional)

Defines the data that is output by the action during a workflow run.

Corresponding UI: Outputs tab

Artifacts - output

(action-name/Outputs/Artifacts)

(Optional)

Specify the name of an artifact generated by the action. Artifact names must be unique within a workflow, and are limited to alphanumeric characters (a-z, A-Z, 0-9) and underscores (_). Spaces, hyphens (-), and other special characters are not allowed. You cannot use quotation marks to enable spaces, hyphens, and other special characters in output artifact names.

For more information about artifacts, including examples, see Sharing artifacts and files between actions.

Corresponding UI: Outputs tab/Artifacts

Name

(action-name/Outputs/Artifacts/Name)

(Required if Artifacts - output is included)

For more information about artifacts, including examples, see Sharing artifacts and files between actions.

Corresponding UI: Outputs tab/Artifacts/New output/Build artifact name

Files

(action-name/Outputs/Artifacts/Files)

(Required if Artifacts - output is included)

Specify the files that CodeCatalyst includes in the artifact that is output by the action. These files are generated by the workflow action when it runs, and are also available in your source repository. File paths can reside in a source repository or an artifact from a previous action, and are relative to the source repository or artifact root. You can use glob patterns to specify paths. Examples:

To specify a single file that is in the root of your build location or source repository location, use my-file.jar.
To specify a single file in a subdirectory, use directory/my-file.jar or directory/subdirectory/my-file.jar.
To specify all files, use "**/*". The ** glob pattern indicates to match any number of subdirectories.
To specify all files and directories in a directory named directory, use "directory/**/*". The ** glob pattern indicates to match any number of subdirectories.
To specify all files in a directory named directory, but not any of its subdirectories, use "directory/*".

Note

If your file path includes one or more asterisks (*) or other special character, enclose the path with double quotation marks (""). For more information about special characters, see Syntax guidelines and conventions.

For more information about artifacts, including examples, see Sharing artifacts and files between actions.

Note

You may need to add a prefix to the file path to indicate which artifact or source to find it in. For more information, see Referencing source repository files and Referencing files in an artifact.

Corresponding UI: Outputs tab/Artifacts/New output/Files produced by build

Variables - output

(action-name/Outputs/Variables)

(Optional)

Specify the variables that you want the action to export so that they are available for use by subsequent actions.

For more information about variables, including examples, see Using variables in workflows.

Corresponding UI: Outputs tab/Variables/Add variable

variable-name-1

(action-name/Outputs/Variables/variable-name-1)

(Optional)

Specify the name of a variable that you want the action to export. This variable must already be defined in the Inputs or Steps section of the same action.

For more information about variables, including examples, see Using variables in workflows.

Corresponding UI: Outputs tab/Variables/Add variable/Name

AutoDiscoverReports

(action-name/Outputs/AutoDiscoverReports)

(Optional)

Defines the configuration for the auto-discovery feature.

When you enable auto-discovery, CodeCatalyst searches all Inputs passed into the action as well as all files generated by the action itself, looking for test, code coverage, and software composition analysis (SCA) reports. For each report that is found, CodeCatalyst transforms it into a CodeCatalyst report. A CodeCatalyst report is a report that is fully integrated into the CodeCatalyst service and can be viewed and manipulated through the CodeCatalyst console.

Note

By default, the auto-discover feature inspects all files. You can limit which files are inspected using the IncludePaths or ExcludePaths properties.

Corresponding UI: Outputs tab/Reports/Auto-discover reports

Enabled

(action-name/Outputs/AutoDiscoverReports/Enabled)

(Optional)

Enable or disable the auto-discovery feature.

Valid values are true or false.

If Enabled is omitted, the default is true.

Corresponding UI: Outputs tab/Reports/Auto-discover reports

ReportNamePrefix

(action-name/Outputs/AutoDiscoverReports/ReportNamePrefix)

(Required if AutoDiscoverReports is included and enabled)

Specify a prefix that CodeCatalyst prepends to all the reports it finds in order to name their associated CodeCatalyst reports. For example, if you specify a prefix of AutoDiscovered, and CodeCatalyst auto-discovers two test reports, TestSuiteOne.xml and TestSuiteTwo.xml, then the associated CodeCatalyst reports will be named AutoDiscoveredTestSuiteOne and AutoDiscoveredTestSuiteTwo.

Corresponding UI: Outputs tab/Reports/Prefix name

IncludePaths

(action-name/Outputs/AutoDiscoverReports/IncludePaths)

(action-name/Outputs/Reports/report-name-1/IncludePaths)

(Required if AutoDiscoverReports is included and enabled, or if Reports is included)

Specify the files and file paths that CodeCatalyst includes when searching for raw reports. For example, if you specify "/test/report/*", CodeCatalyst searches the entire build image used by the action looking for the /test/report/* directory. When it finds that directory, CodeCatalyst then looks for reports in that directory.

Note

If your file path includes one or more asterisks (*) or other special characters, enclose the path with double quotation marks (""). For more information about special characters, see Syntax guidelines and conventions.

If this property is omitted, the default is "**/*", meaning the search includes all files at all paths.

Note

For manually configured reports, IncludePaths must be a glob pattern that matches a single file.

Corresponding UI:

Outputs tab/Reports/Auto-discover reports/Include/exclude paths/Include paths
Outputs tab/Reports/Manually configure reports/report-name-1/Include/exclude paths/Include paths

ExcludePaths

(action-name/Outputs/AutoDiscoverReports/ExcludePaths)

(action-name/Outputs/Reports/report-name-1/ExcludePaths)

(Optional)

Specify the files and file paths that CodeCatalyst excludes when searching for raw reports. For example, if you specify "/test/my-reports/**/*", CodeCatalyst will not search for files in the /test/my-reports/ directory. To ignore all files in a directory, use the **/* glob pattern.

Note

Corresponding UI:

Outputs tab/Reports/Auto-discover reports/Include/exclude paths/Exclude paths
Outputs tab/Reports/Manually configure reports/report-name-1/Include/exclude paths/Exclude paths

SuccessCriteria

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria)

(Optional)

Specify the success criteria for the test, code coverage, software composition analysis (SCA), and static analysis (SA) reports.

For more information, see Configuring success criteria for reports.

Corresponding UI: Output tab/Reports/Success criteria

PassRate

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/PassRate)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/PassRate)

(Optional)

Specify the percentage of tests in a test report that must pass for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: 50, 60.5. The pass rate criteria are applied only to test reports. For more information about test reports, see Test reports.

Corresponding UI: Output tab/Reports/Success criteria/Pass rate

LineCoverage

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/LineCoverage)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/LineCoverage)

(Optional)

Specify the percentage of lines in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: 50, 60.5. Line coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see Code coverage reports.

Corresponding UI: Output tab/Reports/Success criteria/Line coverage

BranchCoverage

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/BranchCoverage)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/BranchCoverage)

(Optional)

Specify the percentage of branches in a code coverage report that must be covered for the associated CodeCatalyst report to be marked as passed. Valid values include decimal numbers. For example: 50, 60.5. Branch coverage criteria are applied only to code coverage reports. For more information about code coverage reports, see Code coverage reports.

Corresponding UI: Output tab/Reports/Success criteria/Branch coverage

Vulnerabilities

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/Vulnerabilities)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/Vulnerabilities)

(Optional)

Specify the maximum number and severity of vulnerabilities permitted in the SCA report for the associated CodeCatalyst report to be marked as passed. To specify vulnerabilities, you must specify:

The minimum severity of the vulnerabilities you want to include in the count. Valid values, from most to least severe, are: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL.

For example, if you choose HIGH, then HIGH and CRITICAL vulnerabilities will be tallied.
The maximum number of vulnerabilities of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Vulnerabilities criteria are applied only to SCA reports. For more information about SCA reports, see Software composition analysis reports.

To specify the minimum severity, use the Severity property. To specify the maximum number of vulnerabilities, use the Number property.

Corresponding UI: Output tab/Reports/Success criteria/Vulnerabilities

StaticAnalysisBug

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/StaticAnalysisBug)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/StaticAnalysisBug)

(Optional)

Specify the maximum number and severity of bugs permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify bugs, you must specify:

The minimum severity of the bugs you want to include in the count. Valid values, from most to least severe, are: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL.

For example, if you choose HIGH, then HIGH and CRITICAL bugs will be tallied.
The maximum number of bugs of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Bugs criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see Static analysis reports.

To specify the minimum severity, use the Severity property. To specify the maximum number of vulnerabilities, use the Number property.

Corresponding UI: Output tab/Reports/Success criteria/Bugs

StaticAnalysisSecurity

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/StaticAnalysisSecurity)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/StaticAnalysisSecurity)

(Optional)

Specify the maximum number and severity of security vulnerabilities permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify security vulnerabilities, you must specify:

The minimum severity of the security vulnerabilities you want to include in the count. Valid values, from most to least severe, are: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL.

For example, if you choose HIGH, then HIGH and CRITICAL security vulnerabilities will be tallied.
The maximum number of security vulnerabilities of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Security vulnerabilities criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see Static analysis reports.

To specify the minimum severity, use the Severity property. To specify the maximum number of vulnerabilities, use the Number property.

Corresponding UI: Output tab/Reports/Success criteria/Security vulnerabilities

StaticAnalysisQuality

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/StaticAnalysisQuality)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/StaticAnalysisQuality)

(Optional)

Specify the maximum number and severity of quality issues permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify quality issues, you must specify:

The minimum severity of the quality issues you want to include in the count. Valid values, from most to least severe, are: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL.

For example, if you choose HIGH, then HIGH and CRITICAL quality issues will be tallied.
The maximum number of quality issues of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Quality issues criteria are applied only to PyLint and ESLint SA reports. For more information about SA reports, see Static analysis reports.

To specify the minimum severity, use the Severity property. To specify the maximum number of vulnerabilities, use the Number property.

Corresponding UI: Output tab/Reports/Success criteria/Quality issues

StaticAnalysisFinding

(action-name/Outputs/AutoDiscoverReports/SuccessCriteria/StaticAnalysisFinding)

(action-name/Outputs/Reports/report-name-1/SuccessCriteria/StaticAnalysisFinding)

(Optional)

Specify the maximum number and severity of findings permitted in the SA report for the associated CodeCatalyst report to be marked as passed. To specify findings, you must specify:

The minimum severity of the findings you want to include in the count. Valid values, from most to least severe, are: CRITICAL, HIGH, MEDIUM, LOW, INFORMATIONAL.

For example, if you choose HIGH, then HIGH and CRITICAL findings will be tallied.
The maximum number of findings of the specified severity you want permit. Exceeding this number causes the CodeCatalyst report to be marked as failed. Valid values are whole numbers.

Findings are applied only to SARIF SA reports. For more information about SA reports, see Static analysis reports.

To specify the minimum severity, use the Severity property. To specify the maximum number of vulnerabilities, use the Number property.

Corresponding UI: Output tab/Reports/Success criteria/Findings

Reports

(action-name/Outputs/Reports )

(Optional)

A section that specifies the configuration for test reports.

Corresponding UI: Outputs tab/Reports

report-name-1

(action-name/Outputs/Reports/report-name-1 )

(Required if Reports is included)

The name you want to give to the CodeCatalyst report that will be generated from your raw reports.

Corresponding UI: Outputs tab/Reports/Manually configure reports/Report name

Format

(action-name/Outputs/Reports/report-name-1/Format)

(Required if Reports is included)

Specify the file format that you're using for your reports. Possible values are as follows.

For test reports:
- For Cucumber JSON, specify Cucumber (visual editor) or CUCUMBERJSON (YAML editor).
- For JUnit XML, specify JUnit (visual editor) or JUNITXML (YAML editor).
- For NUnit XML, specify NUnit (visual editor) or NUNITXML (YAML editor).
- For NUnit 3 XML, specify NUnit3 (visual editor) or NUNIT3XML (YAML editor).
- For Visual Studio TRX, specify Visual Studio TRX (visual editor) or VISUALSTUDIOTRX (YAML editor).
- For TestNG XML, specify TestNG (visual editor) or TESTNGXML (YAML editor).
For code coverage reports:
- For Clover XML, specify Clover (visual editor) or CLOVERXML (YAML editor).
- For Cobertura XML, specify Cobertura (visual editor) or COBERTURAXML (YAML editor).
- For JaCoCo XML, specify JaCoCo (visual editor) or JACOCOXML (YAML editor).
- For SimpleCov JSON generated by simplecov, not simplecov-json, specify Simplecov (visual editor) or SIMPLECOV (YAML editor).
For software composition analysis (SCA) reports:
- For SARIF, specify SARIF (visual editor) or SARIFSCA (YAML editor).

Corresponding UI: Outputs tab/Reports/Manually configure reports/Add/configure reports/report-name-1/Report type and Report format

Configuration

(action-name/Configuration)

(Required) A section where you can define the configuration properties of the action.

Corresponding UI: Configuration tab

Container

(action-name/Configuration/Container)

(Optional)

Specify the Docker image, or container, that the action uses to complete its processing. You can specify one of the active images that come with CodeCatalyst, or you can use your own image. If you choose to use your own image, it can reside in Amazon ECR, Docker Hub, or another registry. If you don't specify a Docker image, the action uses one of the active images for its processing. For information about which active image is used by default, see Active images.

For more information about specifying your own Docker image, see Assigning a custom runtime environment Docker image to an action.

Corresponding UI: Runtime environment Docker image - optional

Registry

(action-name/Configuration/Container/Registry)

(Required if Container is included)

Specify the registry where your image is stored. Valid values include:

CODECATALYST (YAML editor)

The image is stored in the CodeCatalyst registry.
Docker Hub (visual editor) or DockerHub (YAML editor)

The image is stored in the Docker Hub image registry.
Other registry (visual editor) or Other (YAML editor)

The image is stored in a custom image registry. Any publicly available registry can be used.
Amazon Elastic Container Registry (visual editor) or ECR (YAML editor)

The image is stored in an Amazon Elastic Container Registry image repository. To use an image in an Amazon ECR repository, this action needs access to Amazon ECR. To enable this access, you must create an IAM role that includes the following permissions and custom trust policy. (You can modify an existing role to include the permissions and policy, if you want.)

The IAM role must include the following permissions in its role policy:
- ecr:BatchCheckLayerAvailability
- ecr:BatchGetImage
- ecr:GetAuthorizationToken
- ecr:GetDownloadUrlForLayer
The IAM role must include the following custom trust policy:
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "Service":  [
                   "codecatalyst-runner.amazonaws.com",
                   "codecatalyst.amazonaws.com"
                 ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```
For more information about creating IAM roles, see Creating a role using custom trust policies (console) in the IAM User Guide.

Once you have created the role, you must assign it to the action through an environment. For more information, see Associating an environment with an action.

Corresponding UI: Amazon Elastic Container Registry, Docker Hub, and Other registry options

Image

(action-name/Configuration/Container/Image)

(Required if Container is included)

Specify one of the following:

If you are using a CODECATALYST registry, set the image to one of the of the following active images:
- CodeCatalystLinux_x86_64:2024_03
- CodeCatalystLinux_x86_64:2022_11
- CodeCatalystLinux_Arm64:2024_03
- CodeCatalystLinux_Arm64:2022_11
- CodeCatalystLinuxLambda_x86_64:2024_03
- CodeCatalystLinuxLambda_x86_64:2022_11
- CodeCatalystLinuxLambda_Arm64:2024_03
- CodeCatalystLinuxLambda_Arm64:2022_11
- CodeCatalystWindows_x86_64:2022_11
If you are using a Docker Hub registry, set the image to the Docker Hub image name and optional tag.

Example: postgres:latest
If you are using an Amazon ECR registry, set the image to the Amazon ECR registry URI.

Example: 111122223333.dkr.ecr.us-west-2.amazonaws.com/codecatalyst-ecs-image-repo
If you are using a custom registry, set the image to the value expected by the custom registry.

Corresponding UI: Runtime environment docker image (if the registry is CODECATALYST), Docker Hub image (if the registry is Docker Hub), ECR image URL (if the registry is Amazon Elastic Container Registry), and Image URL (if the registry is Other registry).

Steps

(action-name/Configuration/Steps)

(Required)

Specify the shell commands that you want to run during the action to install, configure, and run your build tools.

Here is an example of how to build an npm project:


Steps:
  - Run: npm install
  - Run: npm run build

Here is an example of how to specify file paths:


Steps:
  - Run: cd $ACTION_BUILD_SOURCE_PATH_WorkflowSource/app  && cat file2.txt
  - Run: cd $ACTION_BUILD_SOURCE_PATH_MyBuildArtifact/build-output/  && cat file.txt

For more information about specifying file paths, see Referencing source repository files and Referencing files in an artifact.

Corresponding UI: Configuration tab/Shell commands

Packages

(action-name/Configuration/Packages)

(Optional)

A section where you can specify a package repository that the action uses to resolve dependencies. Packages allow you to securely store and share software packages used for application development.

For more information about packages, see Publish and share software packages in CodeCatalyst.

Corresponding UI: Configuration tab/Packages

NpmConfiguration

(action-name/Configuration/Packages/NpmConfiguration)

(Required if Packages is included)

A section which defines the configuration for the npm package format. This configuration is used by an action during a workflow run.

For more information about the npm package configuration, see Using npm.

Corresponding UI: Configuration tab/Packages/Add configuration/npm

PackageRegistries

(action-name/Configuration/Packages/NpmConfiguration/PackageRegistries)

(Required if Packages is included)

A section where you can define the configuration properties of a sequence of package repositories.

Corresponding UI: Configuration tab/Packages/Add configuration/npm/Add package repository

PackagesRepository

(action-name/Configuration/Packages/NpmConfiguration/PackageRegistries/PackagesRepository)

(Required if Packages is included)

Specify the name of your CodeCatalyst package repository that you want the action to use.

If you specify multiple default repositories, the last repository will take priority.

For more information about package repositories, see Package repositories.

Corresponding UI: Configuration tab/Packages/Add configuration/npm/Add package repository/Package repository

Scopes

(action-name/Configuration/Packages/NpmConfiguration/PackageRegistries/Scopes)

(Optional)

Specify a sequence of scopes that you want to define in your package registry. When defining scopes, the specified package repository is configured as the registry for all listed scopes. If a package with the scope is requested through the npm client, it will use that repository instead of the default. Each scope name must be prefixed with "@".

If you include overriding scopes, the last repository will take priority.

If Scopes is omitted, then the specified package repository is configured as the default registry for all packages used by the action.

For more information about scopes, see Package namespaces and Scoped packages.

Corresponding UI: Configuration tab/Packages/Add configuration/npm/Add package repository/Scopes - optional

ExportAuthorizationToken

(action-name/Configuration/Packages/ExportAuthorizationToken)

(Optional)

Enable or disable the export authorization token feature. If enabled, exported authorization tokens can be used to manually configure a package manager to authenticate with CodeCatalyst package repositories. You can use the token as an environment variable that can be referenced in your actions.

Valid values are true or false.

If ExportAuthorizationToken is omitted, the default is false.

For more information about the export authorization token, see Using authorization tokens in workflow actions.

Corresponding UI: Configuration tab/Packages/Export authorization token

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Tutorial: Upload artifacts to Amazon S3

Testing with workflows