Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md). # Building with workflows Using [CodeCatalyst workflows](workflow.md), you can build applications and other resources. **Topics** + [How do I build an application?](#build-how-to) + [Benefits of the build action](#build-benefits) + [Alternatives to the build action](#build-alternatives) + [Adding the build action](build-add-action.md) + [Viewing the results of a build action](build-view-results.md) + [Tutorial: Upload artifacts to Amazon S3](build-deploy.md) + [Build and test actions YAML](build-action-ref.md) ## How do I build an application? To build an application or resource in CodeCatalyst, you first create a workflow, and then specify a build action inside it. A *build action* is a workflow building block that compiles your source code, runs unit tests, and produces artifacts that are ready to deploy. You add a build action to your workflow using the CodeCatalyst console's visual editor or YAML editor. The high-level steps to build an application or resource are as follows. **To build an application (high-level tasks)** 1. In CodeCatalyst, you **add source code** for an application you want to build. For more information, see [Storing source code in repositories for a project in CodeCatalyst](source-repositories.md). 1. In CodeCatalyst, you **create a workflow**. The workflow is where you define how to build, test, and deploy your application. For more information, see [Getting started with workflows](workflows-getting-started.md). 1. (Optional) In the workflow, you **add a trigger** that indicates the events that will cause the workflow to start automatically. For more information, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md) 1. In the workflow, you add a **build action** that compiles and packages your application or resource source code. Optionally, you can also have the build action run unit tests, generate reports, and deploy your application if you don't want to use a test or deploy action for these purposes. For more on the test and deploy actions, see [Adding the build action](build-add-action.md). 1. (Optional) In the workflow, you **add a test action** and a **deploy action** to test and deploy your application or resource. You can choose from several pre-configured actions to deploy your application to different targets, such as Amazon ECS. For more information, see [Testing with workflowsTesting with workflows](test-workflow-actions.md), and [Deploying with workflowsDeploying with workflows](deploy.md). 1. You **start the workflow** either manually or automatically through a trigger. The workflow runs the build, test, and deploy actions in sequence to build, test, and deploy your application and resources to the target. For more information, see [Starting a workflow run manually](workflows-manually-start.md). ## Benefits of the build action Using the build action within a workflow has the following benefits: + **Fully managed** – The build action eliminates the need to set up, patch, update, and manage your own build servers. + **On demand** – The build action scales on demand to meet your build needs. You pay only for the number of build minutes you consume. For more information, see [Configuring compute and runtime images](workflows-working-compute.md). + **Out of the box** – CodeCatalyst includes prepackaged runtime environment Docker images that are used to run all your workflow actions, including build actions. These images come preconfigured with useful tools for building applications such as the AWS CLI and Node.js. You can configure CodeCatalyst to use a build image that you supply from a public or private registry. For more information, see [Specifying runtime environment images](build-images.md). ## Alternatives to the build action If you're using a build action to deploy your application, consider using a CodeCatalyst *deploy action* instead. Deploy actions perform behind-the-scenes configuration that you would otherwise have to write manually if you're using a build action. For more information on the available deploy actions, see [List of deploy actions](deploy.md#deploy-concepts-action-supported). You can also use AWS CodeBuild to build your applications. For more information, see [What is CodeBuild?](https://docs.aws.amazon.com/codebuild/latest/userguide/welcome.html). # Adding the build action Use the following procedure to add a build action to your CodeCatalyst workflow. ------ #### [ Visual ] **To add a build action using the visual editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **Visual**. 1. Choose **Actions**. 1. In **Actions**, choose **Build**. 1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the [Build and test actions YAML](build-action-ref.md). This reference provides detailed information on each field (and corresponding YAML property value) as it appears in both the YAML and visual editors. 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ #### [ YAML ] **To add a build action using the YAML editor** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. Choose **Edit**. 1. Choose **YAML**. 1. Choose **Actions**. 1. In **Actions**, choose **Build**. 1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the [Build and test actions YAML](build-action-ref.md). 1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing. 1. Choose **Commit**, enter a commit message, and choose **Commit** again. ------ ## Build action definition The build action is defined as a set of YAML properties inside your workflow definition file. For information on these properties, see [Build and test actions YAML](build-action-ref.md) in the [Workflow YAML definition](workflow-reference.md). # Viewing the results of a build action Use the following instructions to view the results of a build action, including the generated logs, reports, and variables. **To view the results of a build action** 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the name of your workflow. You can filter by the source repository or branch name where the workflow is defined, or filter by workflow name or status. 1. In the workflow diagram, choose the name of your build action, for example, **Build**. 1. To view the logs for the build run, choose **Logs**. The logs for the various build phases are displayed. You can expand or collapse the logs as needed. 1. To view the test reports produced by the build action, choose **Reports**, or in the navigation pane, choose **Reports**. For more information, see [Quality report types](test-workflow-actions.md#test-reporting). 1. To view the configuration used for the build action, choose **Configuration**. For more information, see [Adding the build action](build-add-action.md). 1. To view the variables used by the build action, choose **Variables**. For more information, see [Using variables in workflows](workflows-working-with-variables.md). # Tutorial: Upload artifacts to Amazon S3 In this tutorial, you learn how to upload artifacts to an Amazon S3 bucket using an Amazon CodeCatalyst [workflow](workflows-concepts.md#workflows-concepts-workflows) that includes a couple of [build actions](workflows-concepts.md#workflows-concepts-actions). These actions run in series when the workflow starts. The first build action generates two files, `Hello.txt` and `Goodbye.txt`, and bundles them into a build artifact. The second build action uploads the artifact to Amazon S3. You'll configure the workflow to run every time you push a commit to your source repository. **Topics** + [Prerequisites](#build-deploy-tut-prereqs) + [Step 1: Create an AWS role](#build-deploy-tut-role) + [Step 2: Create an Amazon S3 bucket](#build-deploy-tut-artifact) + [Step 3: Create a source repository](#deploy-tut-lambda-cfn-source) + [Step 4: Create a workflow](#build-deploy-tut-workflow.title) + [Step 5: Verify the results](#build-deploy.s3.verify) + [Clean up](#deploy-tut-lambda-cfn-clean-up) ## Prerequisites Before you begin, you need the following: + You need a CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md). + In your space, you need an empty project called: ``` codecatalyst-artifact-project ``` Use the **Start from scratch** option to create this project. For more information, see [Creating an empty project in Amazon CodeCatalyst](projects-create.md#projects-create-empty). + In your project, you need a CodeCatalyst **environment** called: ``` codecatalyst-artifact-environment ``` Configure this environment as follows: + Choose any type, such as **Development**. + Connect your AWS account to it. + For the **Default IAM role**, choose any role. You'll specify a different role later. For more information, see [Deploying into AWS accounts and VPCs](deploy-environments.md). ## Step 1: Create an AWS role In this step, you create an AWS IAM role which you will later assign to the build action in your workflow. This role grants the CodeCatalyst build action permission to access your AWS account and write to Amazon S3 where your artifact will be stored. The role is called the **Build role**. **Note** If you already have a build role that you created for another tutorial, you can use it for this tutorial too. Just make sure it has the permissions and trust policy shown in the following procedure. For more information on IAM roles, see [IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) in the *AWS AWS Identity and Access Management User Guide*. **To create a build role** 1. Create a policy for the role, as follows: 1. Sign in to AWS. 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Policies**. 1. Choose **Create policy**. 1. Choose the **JSON** tab. 1. Delete the existing code. 1. Paste the following code: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": [ "s3:PutObject", "s3:ListBucket" ], "Resource": "*" } ] } ``` ------ **Note** The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available. ``` "Resource": "*" ``` 1. Choose **Next: Tags**. 1. Choose **Next: Review**. 1. In **Name**, enter: ``` codecatalyst-s3-build-policy ``` 1. Choose **Create policy**. You have now created a permissions policy. 1. Create the build role, as follows: 1. In the navigation pane, choose **Roles**, and then choose **Create role**. 1. Choose **Custom trust policy**. 1. Delete the existing custom trust policy. 1. Add the following custom trust policy: 1. Choose **Next**. 1. In **Permissions policies**, search for `codecatalyst-s3-build-policy` and select its check box. 1. Choose **Next**. 1. For **Role name**, enter: ``` codecatalyst-s3-build-role ``` 1. For **Role description**, enter: ``` CodeCatalyst build role ``` 1. Choose **Create role**. You have now created a build role with a trust policy and permissions policy. ## Step 2: Create an Amazon S3 bucket In this step, you create an Amazon S3 bucket where the `Hello.txt` and `Goodbye.txt` artifacts will be uploaded. **To create an Amazon S3 bucket** 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. In the main pane, choose **Create bucket**. 1. For **Bucket name**, enter: ``` codecatalyst-artifact-bucket ``` 1. For **AWS Region**, choose a Region. This tutorial assumes you chose **US West (Oregon) us-west-2**. For information about Regions supported by Amazon S3, see [Amazon Simple Storage Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html) in the *AWS General Reference*. 1. At the bottom of the page, choose **Create bucket**. 1. Copy the name of the bucket you just created, for example: ``` codecatalyst-artifact-bucket ``` You have now created a bucket called **codecatalyst-artifact-bucket** in the US West (Oregon) us-west-2 Region. ## Step 3: Create a source repository In this step, you create a source repository in CodeCatalyst. This repository is used to store the tutorial's workflow definition file. For more information on source repositories, see [Creating a source repository](source-repositories-create.md). **To create a source repository** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to your project, `codecatalyst-artifact-project`. 1. In the navigation pane, choose **Code**, and then choose **Source repositories**. 1. Choose **Add repository**, and then choose **Create repository**. 1. In **Repository name**, enter: ``` codecatalyst-artifact-source-repository ``` 1. Choose **Create**. You have now created a repository called `codecatalyst-artifact-source-repository`. ## Step 4: Create a workflow In this step, you create a workflow that consists of the following building blocks that run sequentially: + A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information on triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md). + A build action called `GenerateFiles` – On trigger, the `GenerateFiles` action creates two files, `Hello.txt` and `Goodbye.txt`, and packages them into an output artifact called `codecatalystArtifact`. + Another build action called `Upload` – On completion of the `GenerateFiles` action, the `Upload` action runs the AWS CLI command `aws s3 sync` to upload the files in the `codecatalystArtifact` and in your source repository to your Amazon S3 bucket. The AWS CLI comes pre-installed and pre-configured on the CodeCatalyst compute platform, so you don't need to install or configure it. For more information on the pre-packaged software on the CodeCatalyst compute platform, see [Specifying runtime environment images](build-images.md). For more information on the AWS CLI's `aws s3 sync` command, see [sync](https://docs.aws.amazon.com/cli/latest/reference/s3/sync.html) in the *AWS CLI Command Reference*. For more information on the build action, see [Building with workflows](build-workflow-actions.md). **To create a workflow** 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose **Create workflow**. 1. Delete the YAML sample code. 1. Add the following YAML code: **Note** In the YAML code that follows, you can omit the `Connections:` section if you want. If you omit this section, you must ensure that the role specified in the **Default IAM role** field in your environment includes the permissions and trust policies described in [Step 1: Create an AWS role](#build-deploy-tut-role). For more information about setting up an environment with a default IAM role, see [Creating an environment](deploy-environments-creating-environment.md). ``` Name: codecatalyst-artifact-workflow SchemaVersion: 1.0 Triggers: - Type: Push Branches: - main Actions: GenerateFiles: Identifier: aws/build@v1 Configuration: Steps: # Create the output files. - Run: echo "Hello, World!" > "Hello.txt" - Run: echo "Goodbye!" > "Goodbye.txt" Outputs: Artifacts: - Name: codecatalystArtifact Files: - "**/*" Upload: Identifier: aws/build@v1 DependsOn: - GenerateFiles Environment: Name: codecatalyst-artifact-environment Connections: - Name: codecatalyst-account-connection Role: codecatalyst-s3-build-role Inputs: Artifacts: - codecatalystArtifact Configuration: Steps: # Upload the output artifact to the S3 bucket. - Run: aws s3 sync . s3://codecatalyst-artifact-bucket ``` In the code above, replace: + *codecatalyst-artifact-environment* with the name of the environment you created in [Prerequisites](#build-deploy-tut-prereqs). + *codecatalyst-account-connection* with the name of the account connection you created in [Prerequisites](#build-deploy-tut-prereqs). + *codecatalyst-s3-build-role* with the name of the build role that you created in [Step 1: Create an AWS role](#build-deploy-tut-role). + *codecatalyst-artifact-bucket* with the name of the Amazon S3 you created in [Step 2: Create an Amazon S3 bucket](#build-deploy-tut-artifact). For information about the properties in this file, see the [Build and test actions YAML](build-action-ref.md). 1. (Optional) Choose **Validate** to make sure the YAML code is valid before committing. 1. Choose **Commit**. 1. On the **Commit workflow** dialog box, enter the following: 1. For **Workflow file name**, leave the default, `codecatalyst-artifact-workflow`. 1. For **Commit message**, enter: ``` add initial workflow file ``` 1. For **Repository**, choose **codecatalyst-artifact-source-repository**. 1. For **Branch name**, choose **main**. 1. Choose **Commit**. You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the `codecatalyst-artifact-workflow.yaml` file to your source repository, the trigger started the workflow run. **To view the workflow run in progress** 1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**. 1. Choose the workflow you just created: `codecatalyst-artifact-workflow`. 1. Choose **GenerateFiles** to see the first build action progress. 1. Choose **Upload** to see the second build action progress. 1. When the **Upload** action finishes, do the following: + If the workflow run succeeded, go to the next procedure. + If the workflow run failed, choose **Logs** to troubleshoot the issue. ## Step 5: Verify the results After the workflow runs, go to the Amazon S3 service and look in your *codecatalyst-artifact-bucket* bucket. It should now include the following files and folders: ``` . |— .aws/ |— .git/ |Goodbye.txt |Hello.txt |REAME.md ``` The `Goodbye.txt` and `Hello.txt` files were uploaded because they were part of the `codecatalystArtifact` artifact. The `.aws/`, `.git/`, and `README.md` files were uploaded because they were in your source repository. ## Clean up Clean up in CodeCatalyst and AWS to avoid being charged for these services. **To clean up in CodeCatalyst** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Delete the `codecatalyst-artifact-source-repository` source repository. 1. Delete the `codecatalyst-artifact-workflow` workflow. **To clean up in AWS** 1. Clean up in Amazon S3, as follows: 1. Open the Amazon S3 console at [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. Delete the files in the `codecatalyst-artifact-bucket` bucket. 1. Delete the `codecatalyst-artifact-bucket` bucket. 1. Clean up in IAM, as follows: 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Delete the `codecatalyst-s3-build-policy`. 1. Delete the `codecatalyst-s3-build-role`. # 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](workflow-reference.md). 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\$1F**. 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 (\$1). 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](workflows-action-versions.md). Use `aws/build@v1` for build actions. Use `aws/managed-test@v1` for test actions. Corresponding UI: Workflow diagram/Action-name/*aws/build@v1\$1aws/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](workflows-depends-on.md). 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](compute-sharing.md). Corresponding UI: *none* ## Type (*action-name*/Compute/**Type**) (Required if [Compute](#build.computename) 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](workflows-working-compute.md#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](workflows-working-compute.md#compute.on-demand). 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](workflows-working-compute.md#compute.provisioned-fleets). 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](workflows-quotas.md). 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](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-vpcs.add.html) 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](deploy-environments-switch-role.md). For more information about environments, see [Deploying into AWS accounts and VPCs](deploy-environments.md) and [Creating an environment](deploy-environments-creating-environment.md). 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](deploy-environments-creating-environment.md). + 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](ipa-connect-account.md). For information about adding an account connection to an environment, see [Creating an environment](deploy-environments-creating-environment.md). Corresponding UI: Configuration tab/Environment/What's in *my-environment*?/three dot menu/**Switch role** ## Name (*action-name*/Environment/Connections/**Name**) (Required if [Connections](#build.environment.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](#build.environment.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](ipa-connect-account-addroles.md). If you do not specify an IAM role, then the action uses the default IAM role listed in the [environment](deploy-environments.md) 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](ipa-iam-roles.md#ipa-iam-roles-service-create). 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](workflows-caching.md). 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](workflows-working-artifacts-ex.md#workflows-working-artifacts-ex-ref-file). 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](workflows-sources.md). 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](workflows-working-artifacts.md). **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 (\$1). 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](workflows-working-with-variables.md). 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 (\$1). 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](workflows-working-artifacts.md). Corresponding UI: Outputs tab/**Artifacts** ## Name (*action-name*/Outputs/Artifacts/**Name**) (Required if [Artifacts - output](#build.outputs.artifacts) is included) 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 (\$1). 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](workflows-working-artifacts.md). Corresponding UI: Outputs tab/Artifacts/New output/**Build artifact name** ## Files (*action-name*/Outputs/Artifacts/**Files**) (Required if [Artifacts - output](#build.outputs.artifacts) 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](workflow-reference.md#workflow.terms.syntax.conv). For more information about artifacts, including examples, see [Sharing artifacts and files between actions](workflows-working-artifacts.md). **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](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md). 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](workflows-working-with-variables.md). 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](workflows-working-with-variables.md). 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](#build.reports.includepaths) or [ExcludePaths](#build.reports.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](#build.outputs.autodiscover) 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**) Or (*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**) (Required if [AutoDiscoverReports](#build.outputs.autodiscover) is included and enabled, or if [Reports](#test.configuration.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](build-images.md) 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](workflow-reference.md#workflow.terms.syntax.conv). 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**) Or (*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** 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](workflow-reference.md#workflow.terms.syntax.conv). 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**) Or (*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](test-config-action.md#test.success-criteria). Corresponding UI: Output tab/Reports/**Success criteria** ## PassRate (*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**PassRate**) Or (*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](test-workflow-actions.md#test-reports). Corresponding UI: Output tab/Reports/Success criteria/**Pass rate** ## LineCoverage (*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**LineCoverage**) Or (*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](test-workflow-actions.md#test-code-coverage-reports). Corresponding UI: Output tab/Reports/Success criteria/**Line coverage** ## BranchCoverage (*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**BranchCoverage**) Or (*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](test-workflow-actions.md#test-code-coverage-reports). Corresponding UI: Output tab/Reports/Success criteria/**Branch coverage** ## Vulnerabilities (*action-name*/Outputs/AutoDiscoverReports/SuccessCriteria/**Vulnerabilities**) Or (*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](test-workflow-actions.md#test-sca-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**) Or (*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](test-workflow-actions.md#test-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**) Or (*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](test-workflow-actions.md#test-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**) Or (*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](test-workflow-actions.md#test-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**) Or (*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](test-workflow-actions.md#test-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](#test.configuration.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](#test.configuration.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](https://github.com/simplecov-ruby/simplecov), not [simplecov-json](https://github.com/vicentllongo/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](build-images.md#build-curated-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](build-images.md#build-curated-images). For more information about specifying your own Docker image, see [Assigning a custom runtime environment Docker image to an action](build-images.md#build-images-specify). 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) 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: For more information about creating IAM roles, see [Creating a role using custom trust policies (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html) 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](deploy-environments-add-app-to-environment.md). 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](build-images.md#build-curated-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](workflows-sources-reference-files.md) and [Referencing files in an artifact](workflows-working-artifacts-refer-files.md). 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](packages.md). Corresponding UI: Configuration tab/**Packages** ## NpmConfiguration (*action-name*/Configuration/Packages/**NpmConfiguration**) (Required if [Packages](#build.configuration.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](packages-npm.md). Corresponding UI: Configuration tab/Packages/Add configuration/**npm** ## PackageRegistries (*action-name*/Configuration/Packages/NpmConfiguration/**PackageRegistries**) (Required if [Packages](#build.configuration.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](#build.configuration.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](packages-concepts.md#packages-concepts-repository). 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](packages-concepts.md#packages-concepts-package-namespaces) and [Scoped packages](https://docs.npmjs.com/cli/v10/using-npm/scope). 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](workflows-package-export-token.md). Corresponding UI: Configuration tab/Packages/**Export authorization token**