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).
# Configuring workflow actions
An *action* is the main building block of a workflow, and defines a logical unit of work, or task, to perform during a workflow run. Typically, a workflow includes multiple actions that run sequentially or in parallel depending on how you've configured them.
**Topics**
+ [
## Action types
](#workflows-actions-types)
+ [
# Adding an action to a workflow
](workflows-add-action.md)
+ [
# Removing an action from a workflow
](workflows-delete-action.md)
+ [
# Developing a custom action
](workflows-custom-action.md)
+ [
# Grouping actions into action groups
](workflows-group-actions.md)
+ [
# Sequencing actions
](workflows-depends-on.md)
+ [
# Sharing artifacts and files between actions
](workflows-working-artifacts.md)
+ [
# Specifying the action version to use
](workflows-action-versions.md)
+ [
# Listing the available action versions
](workflows-action-versions-determine.md)
+ [
# Viewing an action's source code
](workflows-view-source.md)
+ [
# Integrating with GitHub Actions
](integrations-github-actions.md)
## Action types
Within an Amazon CodeCatalyst workflow, you can use the following types of actions.
**Topics**
+ [
### CodeCatalyst actions
](#workflows-actions-types-cc)
+ [
### CodeCatalyst Labs actions
](#workflows-actions-types-cc-labs)
+ [
### GitHub Actions
](#workflows-actions-types-github)
+ [
### Third-party actions
](#workflows-actions-types-3p)
### CodeCatalyst actions
A *CodeCatalyst action* is an action that is authored, maintained, and fully supported by the CodeCatalyst development team.
There are CodeCatalyst actions for building, testing, and deploying applications, as well as for performing miscellaneous tasks, such as invoking an AWS Lambda function.
The following CodeCatalyst actions are available:
+ **Build**
This action builds your artifacts and runs your unit tests in a Docker container. For more information, see [Adding the build action](build-add-action.md).
+ **Test**
This action runs integration and system tests against your application or artifacts. For more information, see [Adding the test action](test-add-action.md).
+ **Amazon S3 publish**
This action copies your application artifacts to an Amazon S3 bucket. For more information, see [Publishing files to Amazon S3 with a workflow](s3-pub-action.md).
+ **AWS CDK bootstrap**
This action provisions the resources that the AWS CDK needs to deploy your CDK app. For more information, see [Bootstrapping an AWS CDK app with a workflow](cdk-boot-action.md).
+ **AWS CDK deploy**
This action synthesizes and deploys an AWS Cloud Development Kit (AWS CDK) app. For more information, see [Deploying an AWS CDK app with a workflow](cdk-dep-action.md).
+ **AWS Lambda invoke**
This action invokes an AWS Lambda function. For more information, see [Invoking a Lambda function using a workflow](lam-invoke-action.md).
+ **GitHub Actions**
This action is a *CodeCatalyst* action that allows you to run GitHub Actions within a CodeCatalyst workflow. For more information, see [Invoking a Lambda function using a workflow](lam-invoke-action.md).
+ **Deploy CloudFormation stack**
This action deploys CloudFormation stacks. For more information, see [Deploying an CloudFormation stack](deploy-action-cfn.md).
+ **Deploy to Amazon ECS**
This action registers an Amazon ECS task definition and deploys it to an Amazon ECS service. For more information, see [Deploying to Amazon ECS with a workflow](deploy-action-ecs.md).
+ **Deploy to Kubernetes cluster**
This action deploys an application to a Kubernetes cluster. For more information, see [Deploying to Amazon EKS with a workflow](deploy-action-eks.md).
+ **Render Amazon ECS task definition**
This action inserts a container image URI into an Amazon ECS task definition JSON file, creating a new task definition file. For more information, see [Modifying an Amazon ECS task definition](render-ecs-action.md).
Documentation for CodeCatalyst actions is available in this guide, and in each action's readme.
For information about the available CodeCatalyst actions, and how to add one to a workflow, see [Adding an action to a workflow](workflows-add-action.md).
### CodeCatalyst Labs actions
A *CodeCatalyst Labs action* is an action that is part of Amazon CodeCatalyst Labs, a proving ground for experimental applications. CodeCatalyst Labs actions have been developed to showcase integrations with AWS services.
The following CodeCatalyst Labs actions are available:
+ **Deploy to AWS Amplify Hosting**
This action deploys an application to Amplify Hosting.
+ **Deploy to AWS App Runner**
This action deploys the latest image in a source image repository to App Runner.
+ **Deploy to Amazon CloudFront and Amazon S3**
This action deploys an application to CloudFront and Amazon S3.
+ **Deploy with AWS SAM**
This action deploys your serverless application with AWS Serverless Application Model (AWS SAM).
+ **Invalidate Amazon CloudFront Cache**
This action invalidates a CloudFront cache for a given set of paths.
+ **Outgoing Webhook**
This action allows users to send messages within a workflow to an arbitrary web server using an HTTPS request.
+ **Publish to AWS CodeArtifact**
This action publishes packages to a CodeArtifact repository.
+ **Publish to Amazon SNS**
This action allows users to integrate with Amazon SNS by creating a topic, publishing to a topic, or subscribing to a topic.
+ **Push to Amazon ECR**
This action builds and publishes a Docker image to an Amazon Elastic Container Registry (Amazon ECR) repository.
+ **Scan with Amazon CodeGuru Security**
This action creates a zip archive of a configured code path and uses CodeGuru Security to run a code scan.
+ **Terraform Community Edition**
This action runs Terraform Community Edition `plan` and `apply` operations.
Documentation for CodeCatalyst Labs actions is available in each action's readme.
For information about adding a CodeCatalyst Labs action to a workflow and viewing its readme, see [Adding an action to a workflow](workflows-add-action.md).
### GitHub Actions
A *GitHub Action* is a lot like a [CodeCatalyst action](#workflows-actions-types-cc), except that it was developed for use with GitHub workflows. For details about GitHub Actions, see the [GitHub Actions](https://docs.github.com/en/actions) documentation.
You can use GitHub Actions alongside native CodeCatalyst actions in a CodeCatalyst workflow.
For your convenience, the CodeCatalyst console provides access to several popular GitHub Actions. You can also use any GitHub Action listed in the [GitHub Marketplace](https://github.com/marketplace/actions) (subject to a few limitations).
Documentation for GitHub Actions is available in each action's readme.
For more information, see [Integrating with GitHub Actions](integrations-github-actions.md).
### Third-party actions
A *third-party action* is an action that is authored by a third-party vendor, and made available in the CodeCatalyst console. Examples of third-party actions include the **Mend SCA** and **SonarCloud Scan** actions, authored by Mend and Sonar, respectively.
Documentation for third-party actions is available in each action's readme. Additional documentation might also be provided by the third-party vendor.
For information about adding a third-party action to a workflow and viewing its readme, see [Adding an action to a workflow](workflows-add-action.md).
# Adding an action to a workflow
Use the following instructions to add an action to a workflow and then configure it.
**To add and configure an action**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. At the top-left, choose **\$1 Actions**, The **Actions** catalog appears.
1. In the drop-down list, do one of the following:
+ Choose **Amazon CodeCatalyst** to view [CodeCatalyst](workflows-actions.md#workflows-actions-types-cc), [CodeCatalyst Labs ](workflows-actions.md#workflows-actions-types-cc-labs), or [third-party](workflows-actions.md#workflows-actions-types-3p) actions.
+ CodeCatalyst actions have a **by AWS** label.
+ CodeCatalyst Labs actions have a **by CodeCatalyst Labs** label.
+ Third-party actions have a **by *vendor*** label, where *vendor* is the name of the third-party vendor.
+ Choose **GitHub** to view a [curated list of GitHub Actions](integrations-github-action-add-curated.md).
1. In the action catalog, search for an action, and then do one of the following:
+ Choose the plus sign (**\$1**) to add the action to your workflow.
+ Choose the action's name to view its readme.
1. Configure the action. Choose **Visual** to use the visual editor, or **YAML** to use the YAML editor. For detailed instructions, see the following links.
For instructions on adding [CodeCatalyst actions](workflows-actions.md#workflows-actions-types-cc), see:
+ [Adding the build action](build-add-action.md)
+ [Adding the test action](test-add-action.md)
+ [Adding the 'Deploy to Amazon ECS' action](deploy-action-ecs-adding.md)
+ [Adding the 'Deploy to Kubernetes cluster' action](deploy-action-eks-adding.md)
+ [Adding the 'Deploy CloudFormation stack' action](deploy-action-cfn-adding.md)
+ [Adding the 'AWS CDK deploy' action](cdk-dep-action-add.md)
+ [Adding the 'AWS CDK bootstrap' action](cdk-boot-action-add.md)
+ [Adding the 'Amazon S3 publish' action](s3-pub-action-add.md)
+ [Adding the 'AWS Lambda invoke' action](lam-invoke-action-add.md)
+ [Adding the 'Render Amazon ECS task definition' action](render-ecs-action-add.md)
For instructions on adding [CodeCatalyst Labs actions](workflows-actions.md#workflows-actions-types-cc-labs), see:
+ The action's readme. You can find the readme by choosing the action's name in the action catalog.
For instructions on adding [GitHub Actions](workflows-actions.md#workflows-actions-types-github), see:
+ [Integrating with GitHub Actions](integrations-github-actions.md)
For instructions on adding [third-party actions](workflows-actions.md#workflows-actions-types-3p), see:
+ The action's readme. You can find the readme by choosing the action's name in the action catalog.
1. (Optional) Choose **Validate** to make sure the YAML code is valid.
1. Choose **Commit** to commit your changes.
# Removing an action from a workflow
Use the following instructions to remove an action from a workflow.
------
#### [ Visual ]
**To remove an action using the visual editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In the workflow diagram, in the action you want to remove, choose the vertical ellipsis icon (![\[Ellipsis.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/elipsis.png)), and choose **Remove**.
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 remove an action using the YAML editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. Find the section of the YAML that contains the action you want to remove.
Select the section and press the delete key on your keyboard.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
# Developing a custom action
You can develop a custom action to use in your workflows using the CodeCatalyst Action Development Kit (ADK). You can then publish the action to the CodeCatalyst actions catalog, so that other CodeCatalyst users can view and use it in their workflows.
**To develop, test, and publish an action (high-level tasks)**
1. Install the required tools and packages necessary to develop an action.
1. Create a CodeCatalyst repository to store your action code.
1. Initialize the action. This lays down the source files required by the action, including an action definition file (`action.yml`) that you can update with your own code.
1. Bootstrap the action code to get the necessary tools and libraries to build, test, and release the action project.
1. Build the action on your local computer, and push the changes to your CodeCatalyst repository.
1. Test the action with unit tests locally, and run the ADK-generated workflow in CodeCatalyst.
1. Publish the action to the CodeCatalyst actions catalog by choosing the **Publish** button in the CodeCatalyst console.
For detailed steps, see the [Amazon CodeCatalyst Action Development Kit Developer Guide](https://docs.aws.amazon.com/codecatalyst/latest/adk/what-is-action-development-kit.html).
# Grouping actions into action groups
An *action group* contains one or more actions. Grouping actions into action groups helps you keep your workflow organized, and also allows you to configure dependencies between different groups.
**Note**
You cannot nest action groups within other action groups or actions.
**Topics**
+ [
## Defining an action group
](#workflows-define-action-group)
+ [
# Example: Defining two action groups
](workflows-group-actions-example.md)
## Defining an action group
Use the following instructions to define an CodeCatalyst action group.
------
#### [ Visual ]
*Not available. Choose YAML to view the YAML instructions.*
------
#### [ YAML ]
**To define a group**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In `Actions`, add code similar to the following:
```
Actions:
action-group-name:
Actions:
action-1:
Identifier: aws/build@v1
Configuration:
...
action-2:
Identifier: aws/build@v1
Configuration:
...
```
For another example, see [Example: Defining two action groups](workflows-group-actions-example.md). For more information, see the description of the `action-group-name` property in the [Actions](workflow-reference.md#actions-reference) of the [Workflow YAML definition](workflow-reference.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.
------
# Example: Defining two action groups
The following example shows how to define two Amazon CodeCatalyst action groups: `BuildAndTest` and `Deploy`. The `BuildAndTest` group includes two actions (`Build` and `Test`), and the `Deploy` group also includes two actions (`DeployCloudFormationStack` and `DeployToECS`).
```
Actions:
BuildAndTest: # Action group 1
Actions:
Build:
Identifier: aws/build@v1
Configuration:
...
Test:
Identifier: aws/managed-test@v1
Configuration:
Deploy: #Action group 2
Actions:
DeployCloudFormationStack:
Identifier: aws/cfn-deploy@v1
Configuration:
...
DeployToECS:
Identifier: aws/ecs-deploy@v1
Configuration:
...
```
# Sequencing actions
By default, when you add actions to a workflow, they are added side by side in the [visual editor](workflow.md#workflow.editors). This means that the actions will run in parallel when you start a workflow run. If you want actions to run in sequential order (and appear vertically in the visual editor), you must set up dependencies between them. For example, you might set up a `Test` action to depend on the `Build` action so that the test action runs after the build action.
You can set up dependencies between actions and action groups. You can also configure one-to-many dependencies so that one action depends on several others in order to start. Consult the guidelines in [Setting up dependencies between actions](workflows-depends-on-set-up.md) to ensure your dependency setup conforms with the workflow's YAML syntax.
**Topics**
+ [
# Examples of how to configure dependencies between actions
](workflows-depends-on-examples.md)
+ [
# Setting up dependencies between actions
](workflows-depends-on-set-up.md)
# Examples of how to configure dependencies between actions
The following examples show how to configure dependencies between actions and groups in the workflow definition file.
**Topics**
+ [
## Example: Configuring a simple dependency
](#workflows-depends-on-example-simple)
+ [
## Example: Configuring an action group to depend on an action
](#workflows-depends-on-example-action-groups-actions)
+ [
## Example: Configuring an action group to depend on another action group
](#workflows-depends-on-example-two-action-groups)
+ [
## Example: Configuring an action group to depend on multiple actions
](#workflows-depends-on-example-advanced)
## Example: Configuring a simple dependency
The following example shows how to configure a `Test` action to depend on the `Build` action using the `DependsOn` property.
```
Actions:
Build:
Identifier: aws/build@v1
Configuration:
...
Test:
DependsOn:
- Build
Identifier: aws/managed-test@v1
Configuration:
...
```
## Example: Configuring an action group to depend on an action
The following example shows how to configure a `DeployGroup` action group to depend on the `FirstAction` action. Notice that action and action group are at the same level.
```
Actions:
FirstAction: #An action outside an action group
Identifier: aws/github-actions-runner@v1
Configuration:
...
DeployGroup: #An action group containing two actions
DependsOn:
- FirstAction
Actions:
DeployAction1:
...
DeployAction2:
...
```
## Example: Configuring an action group to depend on another action group
The following example shows how to configure a `DeployGroup` action group to depend on the `BuildAndTestGroup` action group. Notice that the action groups are at the same level.
```
Actions:
BuildAndTestGroup: # Action group 1
Actions:
BuildAction:
...
TestAction:
...
DeployGroup: #Action group 2
DependsOn:
- BuildAndTestGroup
Actions:
DeployAction1:
...
DeployAction2:
...
```
## Example: Configuring an action group to depend on multiple actions
The following example shows how to configure a `DeployGroup` action group to depend on the `FirstAction` action, the `SecondAction` action, as well as the `BuildAndTestGroup` action group. Notice that `DeployGroup` is at the same level as `FirstAction`, `SecondAction`, and `BuildAndTestGroup`.
```
Actions:
FirstAction: #An action outside an action group
...
SecondAction: #Another action
...
BuildAndTestGroup: #Action group 1
Actions:
Build:
...
Test:
...
DeployGroup: #Action group 2
DependsOn:
- FirstAction
- SecondAction
- BuildAndTestGroup
Actions:
DeployAction1:
...
DeployAction2:
...
```
# Setting up dependencies between actions
Use the following instructions to set up dependencies between actions in a workflow.
When configuring dependencies, follow these guidelines:
+ If an action is inside a group, that action can only depend on other actions within the same group.
+ Actions and action groups can depend on other actions and action groups *at the same level* in the YAML hierarchy, but *not* at a different level.
------
#### [ Visual ]
**To set up dependencies using the visual editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In the workflow diagram, choose the action that will depend on another action.
1. Choose the **Inputs** tab.
1. In **Depends on - optional**, do the following:
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).
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 set up dependencies using the YAML editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In an action that will depend on another, add code similar to the following:
```
action-name:
DependsOn:
- action-1
```
For more examples, see [Examples of how to configure dependencies between actions](workflows-depends-on-examples.md). For general guidelines, see [Setting up dependencies between actions](#workflows-depends-on-set-up). For more information, see the description of the `DependsOn` property in the [Workflow YAML definition](workflow-reference.md) for your action.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
# Sharing artifacts and files between actions
An *artifact* is the output of a workflow action, and typically consists of a folder or archive of files. Artifacts are important because they allow you to share files and information between actions.
For example, you might have a build action that *generates* a `sam-template.yml` file, but you want a deploy action to *use* it. In this scenario, you would use an artifact to allow the build action to share the `sam-template.yml` file with the deploy action. The code might look something like this:
```
Actions:
BuildAction:
Identifier: aws/build@v1
Steps:
- Run: sam package --output-template-file sam-template.yml
Outputs:
Artifacts:
- Name: MYARTIFACT
Files:
- sam-template.yml
DeployAction:
Identifier: aws/cfn-deploy@v1
Inputs:
Artifacts:
- MYARTIFACT
Configuration:
template: sam-template.yml
```
In the previous code, the build action (`BuildAction`) generates a `sam-template.yml` file, and then adds it to an output artifact called `MYARTIFACT`. A subsequent deploy action (`DeployAction`) specifies `MYARTIFACT` as an input, giving it access to the `sam-template.yml` file.
**Topics**
+ [
## Can I share artifacts without specifying them as outputs and inputs?
](#workflows-working-artifacts-share)
+ [
## Can I share artifacts between workflows?
](#workflows-working-artifacts-share-wf)
+ [
# Examples of artifacts
](workflows-working-artifacts-ex.md)
+ [
# Defining an output artifact
](workflows-working-artifacts-output.md)
+ [
# Defining an input artifact
](workflows-working-artifacts-refer.md)
+ [
# Referencing files in an artifact
](workflows-working-artifacts-refer-files.md)
+ [
# Downloading artifacts
](workflows-download-workflow-outputs.md)
## Can I share artifacts without specifying them as outputs and inputs?
Yes, you can share artifacts between actions without specifying them in the `Outputs` and `Inputs` sections of your actions' YAML code. To do this, you must turn on compute sharing. For more information about compute sharing and how to specify artifacts when it is turned on, see [Sharing compute across actions](compute-sharing.md).
**Note**
Although the compute sharing feature allows you to simplify your workflow's YAML code by eliminating the need for the `Outputs` and `Inputs` sections, the feature has limitations that you should be aware of before you turn it on. For information about these limitations, see [Considerations for compute sharing](compute-sharing.md#compare-compute-sharing).
## Can I share artifacts between workflows?
No, you cannot share artifacts between different workflows; however, you can share artifacts between actions within the same workflow.
# Examples of artifacts
The following examples show how to output, input, and reference artifacts in the Amazon CodeCatalyst workflow definition file.
**Topics**
+ [
## Example: Outputting an artifact
](#workflows-working-artifacts-ex-basic)
+ [
## Example: Inputting an artifact generated by another action
](#workflows-working-artifacts-ex-ref)
+ [
## Example: Referencing files in multiple artifacts
](#workflows-working-artifacts-ex-ref-file)
+ [
## Example: Referencing a file in a single artifact
](#workflows-working-artifacts-ex-ref-file-one)
+ [
## Example: Referencing a file in an artifact when a WorkflowSource is present
](#workflows-working-artifacts-ex-ref-file-wf-source)
+ [
## Example: Referencing a file in an artifact when an action group is present
](#workflows-working-artifacts-ex-groups)
## Example: Outputting an artifact
The following example shows how to output an artifact that includes two .jar files.
```
Actions:
Build:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ARTIFACT1
Files:
- build-output/file1.jar
- build-output/file2.jar
```
## Example: Inputting an artifact generated by another action
The following example shows you how to output an artifact called `ARTIFACT4` in `BuildActionA`, and input it into `BuildActionB`.
```
Actions:
BuildActionA:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ARTIFACT4
Files:
- build-output/file1.jar
- build-output/file2.jar
BuildActionB:
Identifier: aws/build@v1
Inputs:
Artifacts:
- ARTIFACT4
Configuration:
```
## Example: Referencing files in multiple artifacts
The following example shows you how to output two artifacts named `ART5` and `ART6` in `BuildActionC`, and then reference two files named `file5.txt` (in artifact `ART5`) and `file6.txt` (in artifact `ART6`) in `BuildActionD` (under `Steps`).
**Note**
For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).
**Note**
Although the example shows the `$CATALYST_SOURCE_DIR_ART5` prefix being used, you could omit it. This is because `ART5` is the *primary input*. To learn more about the primary input, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).
```
Actions:
BuildActionC:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART5
Files:
- build-output/file5.txt
- Name: ART6
Files:
- build-output/file6.txt
BuildActionD:
Identifier: aws/build@v1
Inputs:
Artifacts:
- ART5
- ART6
Configuration:
Steps:
- run: cd $CATALYST_SOURCE_DIR_ART5/build-output && cat file5.txt
- run: cd $CATALYST_SOURCE_DIR_ART6/build-output && cat file6.txt
```
## Example: Referencing a file in a single artifact
The following example shows you how to output one artifact named `ART7` in `BuildActionE`, and then reference `file7.txt` (in artifact `ART7`) in `BuildActionF` (under `Steps`).
Notice how the reference does not require the `$CATALYST_SOURCE_DIR_`*artifact-name* prefix in front of the `build-output` directory as it did in [Example: Referencing files in multiple artifacts](#workflows-working-artifacts-ex-ref-file). This is because there is only one item specified under `Inputs`.
**Note**
For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).
```
Actions:
BuildActionE:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART7
Files:
- build-output/file7.txt
BuildActionF:
Identifier: aws/build@v1
Inputs:
Artifacts:
- ART7
Configuration:
Steps:
- run: cd build-output && cat file7.txt
```
## Example: Referencing a file in an artifact when a WorkflowSource is present
The following example shows you how to output one artifact named `ART8` in `BuildActionG`, and then reference `file8.txt` (in artifact `ART8`) in `BuildActionH` (under `Steps`).
Notice how the reference requires the `$CATALYST_SOURCE_DIR_`*artifact-name* prefix, as it did in [Example: Referencing files in multiple artifacts](#workflows-working-artifacts-ex-ref-file). This is because there are multiple items specified under `Inputs` (a source and an artifact), so you need the prefix to indicate where to look for the file.
**Note**
For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).
```
Actions:
BuildActionG:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART8
Files:
- build-output/file8.txt
BuildActionH:
Identifier: aws/build@v1
Inputs:
Sources:
- WorkflowSource
Artifacts:
- ART8
Configuration:
Steps:
- run: cd $CATALYST_SOURCE_DIR_ART8/build-output && cat file8.txt
```
## Example: Referencing a file in an artifact when an action group is present
The following example shows you how to output an artifact named `ART9` in `ActionGroup1`, `ActionI`, and then reference `file9.txt` (in artifact `ART9`) in `ActionJ`.
For more information on referencing files, see [Referencing files in an artifact](workflows-working-artifacts-refer-files.md).
```
Actions:
ActionGroup1:
Actions:
ActionI:
Identifier: aws/build@v1
Outputs:
Artifacts:
- Name: ART9
Files:
- build-output/file9.yml
ActionJ:
Identifier: aws/cfn-deploy@v1
Inputs:
Sources:
- WorkflowSource
Artifacts:
- ART9
Configuration:
template: /artifacts/ActionGroup1@ActionJ/ART9/build-output/file9.yml
```
# Defining an output artifact
Use the following instructions to define an artifact that you want an Amazon CodeCatalyst action to output. This artifact then becomes available for other actions to use.
**Note**
Not all actions support output artifacts. To determine whether your action supports them, run through the visual editor instructions that follow, and see if the action includes an **Output artifacts** button on the **Outputs** tab. If yes, output artifacts are supported.
------
#### [ Visual ]
**To define an output artifact using the visual editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In the workflow diagram, choose the action that will produce the artifact.
1. Choose the **Outputs** tab.
1. Under **Artifacts**, choose **Add artifact**.
1. Choose **Add artifact**, and enter information into the fields, as follows.
**Build artifact name**
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).
**Files produced by build**
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).
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 define an output artifact using the YAML editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In a workflow action, add code similar to the following:
```
action-name:
Outputs:
Artifacts:
- Name: artifact-name
Files:
- file-path-1
- file-path-2
```
For more examples, see [Examples of artifacts](workflows-working-artifacts-ex.md). For more information, see the [Workflow YAML definition](workflow-reference.md) for your action.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
# Defining an input artifact
If you want to use an artifact generated by another Amazon CodeCatalyst action, you must specify it as an input to the current action. You may be able to specify multiple artifacts as input—it depends on the action. For more information, see the [Workflow YAML definition](workflow-reference.md) for your action.
**Note**
You cannot reference artifacts from other workflows.
Use the following instructions to specify an artifact from another action as input to the current action.
**Prerequisite**
Before you begin, make sure you have output the artifact from the other action. For more information, see [Defining an output artifact](workflows-working-artifacts-output.md). Outputting the artifact makes it available for other actions to use.
------
#### [ Visual ]
**To specify an artifact as input to an action (visual editor)**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In the workflow diagram, choose the action where you want to specify an artifact as input.
1. Choose **Inputs**.
1. In **Artifacts - optional**, do the following:
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.
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 specify an artifact as input to an action (YAML editor)**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In the action where you want to specify the artifact as input, add code similar to the following:
```
action-name:
Inputs:
Artifacts:
- artifact-name
```
For more examples, see [Examples of artifacts](workflows-working-artifacts-ex.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.
------
# Referencing files in an artifact
If you have a file that resides within an artifact, and you need to refer to this file in one of your Amazon CodeCatalyst workflow actions, complete the following procedure.
**Note**
See also [Referencing source repository files](workflows-sources-reference-files.md).
------
#### [ Visual ]
*Not available. Choose YAML to view the YAML instructions.*
------
#### [ YAML ]
**To reference files in an artifact (YAML editor)**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. In the action where you want to reference a file, add code similar to the following:
```
Actions:
My-action:
Inputs:
Sources:
- WorkflowSource
Artifacts:
- artifact-name
Configuration:
template: artifact-path/path/to/file.yml
```
In the previous code, replace:
+ *artifact-name* with the name of the artifact.
+ *artifact-path* with a value from the following table.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-working-artifacts-refer-files.html)
For examples, see [Examples of artifacts](workflows-working-artifacts-ex.md).
**Note**
You can omit the *artifact-path* and just specify the file path relative to the artifact root directory if:
The action where you're including the reference only includes one item under `Inputs` (for example, it includes one input artifact and no source).
The file that you want to reference resides in the primary input. The *primary input* is either the `WorkflowSource`, or the first input artifact listed, if there is no `WorkflowSource`.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
# Downloading artifacts
You can download and inspect artifacts generated by your Amazon CodeCatalyst workflow actions for troubleshooting purposes. There are two types of artifact you can download:
+ **Source artifacts** – An artifact that contains a snapshot of the source repository content as it existed when the run started.
+ **Workflow artifacts** – An artifact defined in the `Outputs` property of your workflow's configuration file.
**To download artifacts output by the workflow**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. Under the workflow's name, choose **Runs**.
1. In **Run history**, in the **Run ID** column, choose a run. For example, `Run-95a4d`.
1. Under the run's name, choose **Artifacts**.
1. Next to an artifact, choose **Download**. An archive file downloads. Its file name consists of seven random characters.
1. Extract the archive using an archive extraction utility of your choice.
# Specifying the action version to use
By default, when you add an action to a workflow, Amazon CodeCatalyst adds the full version to the workflow definition file using the format:
`vmajor.minor.patch`
For example:
```
My-Build-Action:
Identifier: aws/build@v1.0.0
```
You can shorten the full version in the `Identifier` property so that the workflow always uses the latest minor or patch version of the action.
For example, if you specify:
```
My-CloudFormation-Action:
Identifier: aws/cfn-deploy@v1.0
```
...and the latest patch version is `1.0.4`, then the action will use `1.0.4`. If a later version is released, say `1.0.5`, then the action will use `1.0.5`. If a minor version is released, say `1.1.0`, then the action will continue to use `1.0.5`.
For detailed instructions on specifying versions, see one of the following topics.
Use the following instructions to indicate which version of an action you want your workflow to use. You can specify the latest major or minor version, or a specific patch version.
We recommend using the latest minor or patch version of an action.
------
#### [ Visual ]
*Not available. Choose YAML to view the YAML instructions.*
------
#### [ YAML ]
**To configure a workflow to use the latest version of an action, or a specific patch version**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. Find the action whose version you want to edit.
1. Find the action's `Identifier` property, and set the version to one of the following:
+ action-identifier@v*major* – Use this syntax to have the workflow use a specific major version, and allow the latest minor and patch versions to be chosen automatically.
+ action-identifier@v*major*.*minor* – Use this syntax to have the workflow use a specific minor version, and allow the latest patch version to be chosen automatically.
+ action-identifier@v*major*.*minor*.*patch* – Use this syntax to have the workflow use a specific patch version.
**Note**
If you're not sure which versions are available, see [Listing the available action versions](workflows-action-versions-determine.md).
**Note**
You cannot omit the major version.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
# Listing the available action versions
Use the following instructions to determine which versions of an action are available for you to use in a workflow.
------
#### [ Visual ]
**To determine which action versions are available**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. Find the action whose versions you want to view:
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the name of any workflow, or create one. For information about creating a workflow, see [Creating a workflow](workflows-create-workflow.md).
1. Choose **Edit**.
1. At the top-left, choose **\$1 Actions** to open the action catalog.
1. In the drop-down list, choose **Amazon CodeCatalyst** to view CodeCatalyst, CodeCatalyst Labs, and third-party actions, or choose **GitHub** to view curated GitHub Actions.
1. Search for an action, and choose its name. Do not choose the plus sign (**\$1**).
Details about the action appear.
1. In the action details dialog box, near the top-right, choose the **Versions** drop-down list to see a list of available versions of the action.
------
#### [ YAML ]
*Not available. Choose 'visual' to view the visual editor instructions.*
------
# Viewing an action's source code
You can view an action's source code to make sure it doesn't contain risky code, security vulnerabilities, or other defects.
Use the following instructions to view the source code of a [CodeCatalyst](workflows-actions.md#workflows-actions-types-cc), [CodeCatalyst Labs](workflows-actions.md#workflows-actions-types-cc-labs), or [third-party](workflows-actions.md#workflows-actions-types-3p) action.
**Note**
To view the source code of a [GitHub Action](workflows-actions.md#workflows-actions-types-github), go to the action's page in the [GitHub Marketplace](https://github.com/marketplace/actions). The page includes a link to the action's repository, where you can find the action's source code.
**Note**
You cannot view the source code of the following CodeCatalyst actions: [build](build-workflow-actions.md), [test](test-workflow-actions.md), [GitHub Actions](integrations-github-action-add.md).
**Note**
AWS does not support or guarantee the action code of GitHub Actions or third-party actions.
**To view an action's source code**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
1. Find the action whose code you want to view:
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose the name of any workflow, or create one. For information about creating a workflow, see [Creating a workflow](workflows-create-workflow.md).
1. Choose **Edit**.
1. At the top-left, choose **\$1 Actions** to open the action catalog.
1. In the drop-down list, choose **Amazon CodeCatalyst** to view CodeCatalyst, CodeCatalyst Labs, and third-party actions.
1. Search for an action, and choose its name. Do not choose the plus sign (**\$1**).
Details about the action appear.
1. In the action details dialog box, near the bottom, choose **Download**.
A page appears, showing the Amazon S3 bucket where the action's source code resides. For information about Amazon S3, see [What is Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) in the *Amazon Simple Storage Service User Guide*.
1. Inspect the code to ensure it meets your expectations for quality and security.
# Integrating with GitHub Actions
A *GitHub Action* is a lot like a [CodeCatalyst action](workflows-actions.md#workflows-actions-types-cc), except that it was developed for use with GitHub workflows. For details about GitHub Actions, see the [GitHub Actions](https://docs.github.com/en/actions) documentation.
You can use GitHub Actions alongside native CodeCatalyst actions in a CodeCatalyst workflow.
There are two ways to add a GitHub Action to a CodeCatalyst workflow:
+ You can select the GitHub Action from a curated list in the CodeCatalyst console. Several popular GitHub Actions are available. For more information, see [Adding a curated GitHub Action](integrations-github-action-add-curated.md).
+ If the GitHub Action that you want to use is not available in the CodeCatalyst console, you can add it using a **GitHub Actions** action.
A ***GitHub Actions*** action is a *CodeCatalyst action* that wraps a GitHub Action and makes it compatible with CodeCatalyst workflows.
Here is an example of a **GitHub Actions** action wrapping the [Super-Linter](https://github.com/marketplace/actions/super-linter) GitHub Action:
```
Actions:
GitHubAction:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: "true"
DEFAULT_BRANCH: main
```
In the previous code, the CodeCatalyst **GitHub Actions** action (identified by `aws/github-actions-runner@v1`) wraps the Super-Linter action (identified by `github/super-linter@v4`), making it work in a CodeCatalyst workflow.
For more information, see [Adding the 'GitHub Actions' action](integrations-github-action-add.md).
All GitHub Actions—both curated and not—must be wrapped inside a **GitHub Actions** action (`aws/github-actions-runner@v1`), as shown in the previous example. The wrapper is required for the action to function properly.
**Topics**
+ [
## How are GitHub Actions different from CodeCatalyst actions?
](#integrations-github-actions-how-different)
+ [
## Can GitHub Actions interact with other CodeCatalyst actions in the workflow?
](#integrations-github-actions-interactions.title)
+ [
## Which GitHub Actions can I use?
](#integrations-github-actions-supported)
+ [
## Limitations of GitHub Actions in CodeCatalyst
](#integrations-github-actions-limitations)
+ [
## How do I add a GitHub Action (high-level steps)?
](#integrations-github-actions-how-to)
+ [
## Does the GitHub Action run in GitHub?
](#integrations-github-actions-where-it-runs)
+ [
## Can I use GitHub workflows too?
](#integrations-github-actions-workflows-support.title)
+ [
## Runtime image used by the 'GitHub Actions' action
](#integrations-github-actions-runtime)
+ [
# Tutorial: Lint code using a GitHub Action
](integrations-github-action-tutorial.md)
+ [
# Adding the 'GitHub Actions' action
](integrations-github-action-add.md)
+ [
# Adding a curated GitHub Action
](integrations-github-action-add-curated.md)
+ [
# Exporting GitHub output parameters
](integrations-github-action-export.md)
+ [
# Referencing GitHub output parameters
](integrations-github-action-referencing.md)
+ [
# 'GitHub Actions' action YAML
](github-action-ref.md)
## How are GitHub Actions different from CodeCatalyst actions?
GitHub Actions that are used inside a CodeCatalyst workflow do not have the same level of access and integration with AWS and CodeCatalyst features (such as [environments](deploy-environments.md) and [issues](issues.md)) that CodeCatalyst actions do.
## Can GitHub Actions interact with other CodeCatalyst actions in the workflow?
Yes. For example, GitHub Actions can use variables produced by other CodeCatalyst actions as input, and can also share output parameters and artifacts with CodeCatalyst actions. For more information, see [Exporting GitHub output parameters](integrations-github-action-export.md) and [Referencing GitHub output parameters](integrations-github-action-referencing.md).
## Which GitHub Actions can I use?
You can use any GitHub Action available through the CodeCatalyst console, and any GitHub Action available in the [GitHub Marketplace](https://github.com/marketplace/actions). If you decide to use a GitHub Action from the Marketplace, keep in mind the following [limitations](#integrations-github-actions-limitations).
## Limitations of GitHub Actions in CodeCatalyst
+ GitHub Actions cannot be used with the CodeCatalyst [Lambda compute type](workflows-working-compute.md#compute.types).
+ GitHub Actions run on the [November 2022](build-images.md#build.previous-image) runtime environment Docker image, which includes older tooling. For more information about the image and tooling, see [Specifying runtime environment images](build-images.md).
+ GitHub Actions that internally rely on the [`github` context](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context) or that reference GitHub-specific resources won't work in CodeCatalyst. For example, the following actions won't work in CodeCatalyst:
+ Actions that attempt to add, change, or update GitHub resources. Examples include actions that update pull requests, or create issues in GitHub.
+ Almost all actions listed in [https://github.com/actions](https://github.com/actions).
+ GitHub Actions that are [Docker container actions](https://docs.github.com/en/actions/creating-actions/about-custom-actions#docker-container-actions) will work, but they must be run by the default Docker user (root). Do not run the action as user 1001. (At the time of writing, user 1001 works in GitHub, but not in CodeCatalyst.) For more information, see the [USER](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions#user) topic in [Dockerfile support for GitHub Actions](https://docs.github.com/en/actions/creating-actions/dockerfile-support-for-github-actions).
For a list of GitHub Actions available through the CodeCatalyst console, see [Adding a curated GitHub Action](integrations-github-action-add-curated.md).
## How do I add a GitHub Action (high-level steps)?
The high-level steps to add a GitHub Action to a CodeCatalyst workflow are as follows:
1. In your CodeCatalyst project, 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. In the workflow, you **add a curated GitHub Action** or you **add the GitHub Actions** action.
1. You do one of the following:
+ If you chose to add a curated action, configure it. For more information, see [Adding a curated GitHub Action](integrations-github-action-add-curated.md).
+ If you chose to add a non-curated action, within the **GitHub Actions** action, you **paste the GitHub Action’s YAML code**. You can find this code on the details page of your chosen GitHub Action in the [GitHub Marketplace](https://github.com/marketplace/actions). You will likely need to modify the code slightly to have it work in CodeCatalyst. For more information, see [Adding the 'GitHub Actions' action](integrations-github-action-add.md).
1. (Optional) Within the workflow, **you add other actions** like the build and test actions. For more information, see [Build, test, and deploy with workflowsBuild, test, and deploy with workflows](workflow.md).
1. You **start the workflow** either manually or automatically through a trigger. The workflow runs the GitHub Action and any other actions in the workflow. For more information, see [Starting a workflow run manually](workflows-manually-start.md).
For detailed steps, see:
+ [Adding a curated GitHub Action](integrations-github-action-add-curated.md).
+ [Adding the 'GitHub Actions' action](integrations-github-action-add.md).
## Does the GitHub Action run in GitHub?
No. The GitHub Action runs in CodeCatalyst, using CodeCatalyst’s [runtime environment image](workflows-working-compute.md).
## Can I use GitHub workflows too?
No.
## Runtime image used by the 'GitHub Actions' action
The CodeCatalyst **GitHub Actions** action runs on a [November 2022 image](build-images.md#build.previous-image). For more information, see [Active images](build-images.md#build-curated-images).
# Tutorial: Lint code using a GitHub Action
In this tutorial, you add the [Super-Linter GitHub Action](https://github.com/marketplace/actions/super-linter) to an Amazon CodeCatalyst workflow. The Super-Linter action inspects code, finds areas where the code has errors, formatting issues, and suspicious constructs, and then outputs the results to the CodeCatalyst console). After adding the linter to your workflow, you run the workflow to lint a sample Node.js application (`app.js`). You then fix the reported problems and run the workflow again to see if the fixes worked.
**Tip**
Consider using Super-Linter to lint YAML files, such as [CloudFormation templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-guide.html).
**Topics**
+ [
## Prerequisites
](#integrations-github-action-tutorial-prereqs)
+ [
## Step 1: Create a source repository
](#integrations-github-action-tutorial-create-source-repo)
+ [
## Step 2: Add an app.js file
](#integrations-github-action-tutorial-add-appjs)
+ [
## Step 3: Create a workflow that runs the Super-Linter action
](#integrations-github-action-tutorial-create-workflow)
+ [
## Step 4: Fix problems that the Super-Linter found
](#integrations-github-action-tutorial-fix-probs)
+ [
## Clean up
](#integrations-github-action-tutorial-cleanup)
## Prerequisites
Before you begin, you'll need:
+ A CodeCatalyst **space** with a connected AWS account. For more information, see [Creating a space](spaces-create.md).
+ An empty project in your CodeCatalyst space called `codecatalyst-linter-project`. Choose 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).
## Step 1: Create a source repository
In this step, you create a source repository in CodeCatalyst. You'll use this repository to store the sample application source file, `app.js`, for this tutorial.
For more information about 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-linter-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-linter-source-repository
```
1. Choose **Create**.
## Step 2: Add an app.js file
In this step, you add an `app.js` file to your source repository. The `app.js` contains function code that has a few mistakes that the linter will find.
**To add the app.js file**
1. In the CodeCatalyst console, choose your project, `codecatalyst-linter-project`.
1. In the navigation pane, choose **Code**, and then choose **Source repositories**.
1. From the list of source repositories, choose your repository, `codecatalyst-linter-source-repository`.
1. In **Files**, choose **Create file**.
1. In the text box, enter the following code:
```
// const axios = require('axios')
// const url = 'http://checkip.amazonaws.com/';
let response;
/**
*
* Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format
* @param {Object} event - API Gateway Lambda Proxy Input Format
*
* Context doc: https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-context.html
* @param {Object} context
*
* Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
* @returns {Object} object - API Gateway Lambda Proxy Output Format
*
*/
exports.lambdaHandler = async (event, context) => {
try {
// const ret = await axios(url);
response = {
statusCode: 200,
'body': JSON.stringify({
message: 'hello world'
// location: ret.data.trim()
})
}
} catch (err) {
console.log(err)
return err
}
return response
}
```
1. For **File name**, enter `app.js`. Keep the other default options.
1. Choose **Commit**.
You have now created a file called `app.js`.
## Step 3: Create a workflow that runs the Super-Linter action
In this step, you create a workflow that runs the Super-Linter action when you push code to your source repository. The workflow consists of the following building blocks, which you define in a YAML file:
+ **A trigger** – This trigger starts the workflow run automatically when you push a change to your source repository. For more information about triggers, see [Starting a workflow run automatically using triggers](workflows-add-trigger.md).
+ **A 'GitHub Actions' action** – On trigger, the **GitHub Actions** action runs the Super-Linter action, which in turn inspects all files in your source repository. If the linter finds an issue, the workflow action fails.
**To create a workflow that runs the Super-Linter action**
1. In the CodeCatalyst console, choose your project, `codecatalyst-linter-project`.
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. Choose **Create workflow**.
1. For **Source repository**, choose `codecatalyst-linter-source-repository`.
1. For **Branch**, choose `main`.
1. Choose **Create**.
1. Delete the YAML sample code.
1. Add the following YAML:
```
Name: codecatalyst-linter-workflow
SchemaVersion: "1.0"
Triggers:
- Type: PUSH
Branches:
- main
Actions:
SuperLinterAction:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
github-action-code
```
In the preceding code, replace *github-action-code* with the Super-Linter action code, as instructed in the following steps of this procedure.
1. Go to the [Super-Linter page](https://github.com/marketplace/actions/super-linter) in the GitHub Marketplace.
1. Under `steps:`(lowercase), find the code and paste it into the CodeCatalyst workflow under `Steps:` (uppercase).
Adjust the GitHub Action code to conform to CodeCatalyst standards, as shown in the following code.
Your CodeCatalyst workflow now looks like this:
```
Name: codecatalyst-linter-workflow
SchemaVersion: "1.0"
Triggers:
- Type: PUSH
Branches:
- main
Actions:
SuperLinterAction:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: "true"
DEFAULT_BRANCH: main
```
1. (Optional) Choose **Validate** to make sure the YAML code is valid before committing.
1. Choose **Commit**, enter a **Commit message**, select your `codecatalyst-linter-source-repository` **Repository**, and choose **Commit** again.
You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow.
**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-linter-workflow`.
1. In the workflow diagram, choose **SuperLinterAction**.
1. Wait for the action to fail. This failure is expected because the linter found problems in the code.
1. Leave the CodeCatalyst console open and go to [Step 4: Fix problems that the Super-Linter found](#integrations-github-action-tutorial-fix-probs).
## Step 4: Fix problems that the Super-Linter found
The Super-Linter should have found problems in the `app.js` code, as well as the `README.md` file included in your source repository.
**To fix the problems the linter found**
1. In the CodeCatalyst console, choose the **Logs** tab, and then choose **Lint Code Base**.
The logs that the Super-Linter action generated are displayed.
1. In the Super-Linter logs, scroll down to around line 90, where you find the start of the problems. They look similar to the following:
```
/github/workspace/hello-world/app.js:3:13: Extra semicolon.
/github/workspace/hello-world/app.js:9:92: Trailing spaces not allowed.
/github/workspace/hello-world/app.js:21:7: Unnecessarily quoted property 'body' found.
/github/workspace/hello-world/app.js:31:1: Expected indentation of 2 spaces but found 4.
/github/workspace/hello-world/app.js:32:2: Newline required at end of file but not found.
```
1. Fix `app.js` and `README.md` in your source repository and commit your changes.
**Tip**
To fix the `README.md`, add `markdown` to the code block, like this:
```
```markdown
Setup examples:
...
```
```
Your changes start another workflow run automatically. Wait for the workflow to finish. If you fixed all the problems, the workflow should succeed.
## Clean up
Clean up in CodeCatalyst to remove traces of this tutorial from your environment.
**To clean up in CodeCatalyst**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Delete `codecatalyst-linter-source-repository`.
1. Delete `codecatalyst-linter-workflow`.
In this tutorial, you learned how to add the Super-Linter GitHub Action to a CodeCatalyst workflow in order to lint some code.
# Adding the 'GitHub Actions' action
A ***GitHub Actions*** action is a *CodeCatalyst action* that wraps a GitHub Action and makes it compatible with CodeCatalyst workflows.
For more information, see [Integrating with GitHub Actions](integrations-github-actions.md).
To add the **GitHub Actions** action to a workflow, follow these steps.
**Tip**
For a tutorial that shows you how to use the **GitHub Actions** action, see [Tutorial: Lint code using a GitHub Action](integrations-github-action-tutorial.md).
------
#### [ Visual ]
**To add the 'GitHub Actions' action using the visual editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. At the top-left, choose **\$1 Actions** to open the action catalog.
1. From the drop-down list, choose **GitHub**.
1. Search for the **GitHub Actions** action, and do one of the following:
+ Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.
Or
+ Choose **GitHub Actions**. The action details dialog box appears. On this dialog box:
+ (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
+ Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.
1. In the **Inputs** and **Configuration** tabs, complete the fields according to your needs. For a description of each field, see the ['GitHub Actions' action YAML](github-action-ref.md). This reference provides detailed information about 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 the 'GitHub Actions' action using the YAML editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. At the top-left, choose **\$1 Actions** to open the action catalog.
1. From the drop-down list, choose **GitHub**.
1. Search for the **GitHub Actions** action, and do one of the following:
+ Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.
Or
+ Choose **GitHub Actions**. The action details dialog box appears. On this dialog box:
+ (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
+ Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.
1. Modify the properties in the YAML code according to your needs. An explanation of each available property is provided in the ['GitHub Actions' action YAML](github-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.
------
## 'GitHub Actions' action definition
The **GitHub Actions** action is defined as a set of YAML properties inside your workflow definition file. For information about these properties, see ['GitHub Actions' action YAML](github-action-ref.md) in the [Workflow YAML definition](workflow-reference.md).
# Adding a curated GitHub Action
A *curated GitHub Action* is a GitHub Action that is made available in the CodeCatalyst console, and serves as an example of how to use a GitHub Action inside a CodeCatalyst workflow.
Curated GitHub Actions are wrapped in the CodeCatalyst-authored [**GitHub Actions** action](integrations-github-action-add.md), identified by the `aws/github-actions-runner@v1` identifier. For example, here's what the curated GitHub Action, [TruffleHog OSS](https://github.com/marketplace/actions/trufflehog-oss), looks like:
```
Actions:
TruffleHogOSS_e8:
Identifier: aws/github-actions-runner@v1
Inputs:
Sources:
- WorkflowSource # This specifies that the action requires this Workflow as a source
Configuration:
Steps:
- uses: trufflesecurity/trufflehog@v3.16.0
with:
path: ' ' # Required; description: Repository path
base: ' ' # Required; description: Start scanning from here (usually main branch).
head: ' ' # Optional; description: Scan commits until here (usually dev branch).
extra_args: ' ' # Optional; description: Extra args to be passed to the trufflehog cli.
```
In the previous code, the CodeCatalyst **GitHub Actions** action (identified by `aws/github-actions-runner@v1`) wraps the TruffleHog OSS action (identified by `trufflesecurity/trufflehog@v3.16.0`), making it work in a CodeCatalyst workflow.
To configure this action, you would replace the empty strings under `with:` with your own values. For example:
```
Actions:
TruffleHogOSS_e8:
Identifier: aws/github-actions-runner@v1
Inputs:
Sources:
- WorkflowSource # This specifies that the action requires this Workflow as a source
Configuration:
Steps:
- uses: trufflesecurity/trufflehog@v3.16.0
with:
path: ./
base: main # Required; description: Start scanning from here (usually main branch).
head: HEAD # Optional; description: Scan commits until here (usually dev branch).
extra_args: '‐‐debug ‐‐only-verified' # Optional; description: Extra args to be passed to the trufflehog cli.
```
To add a curated GitHub Action to a workflow, use the following procedure. For general information about using GitHub Actions in a CodeCatalyst workflow, see [Integrating with GitHub Actions](integrations-github-actions.md).
**Note**
If you don't see your GitHub Action among the list of curated actions, you can still add it to your workflow using the **GitHub Actions** action. For more information, see [Adding the 'GitHub Actions' action](integrations-github-action-add.md).
------
#### [ Visual ]
**To add a curated GitHub action using the visual editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. At the top-left, choose **\$1 Actions** to open the action catalog.
1. From the drop-down list, choose **GitHub**.
1. Browse or search for a GitHub Action, and do one of the following:
+ Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.
Or
+ Choose the name of the GitHub Action. The action details dialog box appears. On this dialog box:
+ (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
+ Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.
1. In the **Inputs**, **Configuration**, and **Outputs** tabs, complete the fields according to your needs. For a description of each field, see the ['GitHub Actions' action YAML](github-action-ref.md). This reference provides detailed information about each field (and corresponding YAML property value) available to the **GitHub Actions** action, as it appears in both the YAML and visual editors.
For information about the configuration options available to the curated GitHub Action, see its documentation.
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 curated GitHub action using the YAML editor**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Choose your project.
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. At the top-left, choose **\$1 Actions** to open the action catalog.
1. From the drop-down list, choose **GitHub**.
1. Browse or search for a GitHub Action, and do one of the following:
+ Choose the plus sign (**\$1**) to add the action to the workflow diagram and open its configuration pane.
Or
+ Choose the name of the GitHub Action. The action details dialog box appears. On this dialog box:
+ (Optional) Choose **View source** to [view the action's source code](workflows-view-source.md#workflows-view-source.title).
+ Choose **Add to workflow** to add the action to the workflow diagram and open its configuration pane.
1. Modify the properties in the YAML code according to your needs. An explanation of each property available to the **GitHub Actions** action is provided in the ['GitHub Actions' action YAML](github-action-ref.md).
For information about the configuration options available to the curated GitHub Action, see its documentation.
1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.
1. Choose **Commit**, enter a commit message, and choose **Commit** again.
------
# Exporting GitHub output parameters
You can use [GitHub output parameters](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter) in your CodeCatalyst workflows.
**Note**
Another word for *output parameter* is *variable*. Because GitHub uses the term *output parameter* in its documentation, we'll use this term too.
Use the following instructions to export a GitHub output parameter from a GitHub Action so that it is available for use by other CodeCatalyst workflow actions.
**To export a GitHub output parameter**
1. Open a workflow and choose **Edit**. For more information, see [Creating a workflow](workflows-create-workflow.md).
1. In the **GitHub Actions** action that generates the output parameter that you want to export, add an `Outputs` section with an underlying `Variables` property that looks like this:
```
Actions:
MyGitHubAction:
Identifier: aws/github-actions-runner@v1
Outputs:
Variables:
- 'step-id_output-name'
```
Replace:
+ *step-id* with value of the `id:` property in the GitHub action's `steps` section.
+ *output-name* with the name of the GitHub output parameter.
**Example**
The following example shows you how to export a GitHub output parameter called `SELECTEDCOLOR`.
```
Actions:
MyGitHubAction:
Identifier: aws/github-actions-runner@v1
Outputs:
Variables:
- 'random-color-generator_SELECTEDCOLOR'
Configuration:
Steps:
- name: Set selected color
run: echo "SELECTEDCOLOR=green" >> $GITHUB_OUTPUT
id: random-color-generator
```
# Referencing GitHub output parameters
Use the following instructions to reference a GitHub output parameter.
**To reference a GitHub output parameter**
1. Complete the steps in [Exporting GitHub output parameters](integrations-github-action-export.md).
The GitHub output parameter is now available for use in other actions.
1. Note the output parameter's `Variables` value. It includes an underscore (\$1).
1. Refer to the output parameter using the following syntax:
```
${action-name.output-name}
```
Replace:
+ *action-name* with the name of the CodeCatalyst **GitHub Action** that produces the output parameter (do not use the GitHub action's `name` or `id`).
+ *output-name* with the output parameter's `Variables` value you noted earlier.
**Example**
```
BuildActionB:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: echo ${MyGitHubAction.random-color-generator_SELECTEDCOLOR}
```
**Example with context**
The following example shows you how to set a `SELECTEDCOLOR` variable in `GitHubActionA`, output it, and then refer to it in `BuildActionB`.
```
Actions:
GitHubActionA:
Identifier: aws/github-actions-runner@v1
Configuration:
Steps:
- name: Set selected color
run: echo "SELECTEDCOLOR=green" >> $GITHUB_OUTPUT
id: random-color-generator
Outputs:
Variables:
- 'random-color-generator_SELECTEDCOLOR'
BuildActionB:
Identifier: aws/build@v1
Configuration:
Steps:
- Run: echo ${GitHubActionA.random-color-generator_SELECTEDCOLOR}
```
# 'GitHub Actions' action YAML
The following is the YAML definition of the **GitHub Actions** action.
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/github-actions-runner@v1
DependsOn:
- dependent-action-name-1
Compute:
Fleet: fleet-name
Timeout: timeout-minutes
Environment:
Name: environment-name
Connections:
- Name: account-connection-name
Role: iam-role-name
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:
- github-output/artifact-1.jar
- "github-output/build*"
- Name: output-artifact-2
Files:
- github-output/artifact-2.1.jar
- github-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
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
Configuration
Steps:
- github-actions-code
```
## 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/github-actions-runner@v1` for **GitHub Actions** actions.
Corresponding UI: Workflow diagram/*action-name*/**aws/github-actions-runner@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*
## 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 - optional**
## 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**)
(Required if [Environment](#github.environment) is included)
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](#github.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](#github.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 **GitHub Action** action. 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**
## 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 **GitHub Actions** 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: Inputs tab/**Sources - optional**
## 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](#github.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/Add artifact/**Build artifact name**
## Files
(*action-name*/Outputs/Artifacts/**Files**)
(Required if [Artifacts - output](#github.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/Add artifact/**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](#github.reports.includepaths) or [ExcludePaths](#github.reports.excludepaths) properties.
Corresponding UI: *none*
## 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/**Automatically discover reports**
## ReportNamePrefix
(*action-name*/Outputs/AutoDiscoverReports/**ReportNamePrefix**)
(Required if [AutoDiscoverReports](#github.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/Automatically discover reports/**Report prefix**
## IncludePaths
(*action-name*/Outputs/AutoDiscoverReports/**IncludePaths**)
Or
(*action-name*/Outputs/Reports/*report-name-1*/**IncludePaths**)
(Required if [AutoDiscoverReports](#github.outputs.autodiscover) is included and enabled, or if [Reports](#github.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/Automatically 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/Automatically 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:
+ Outputs tab/Reports/Automatically discover reports/**Success criteria**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/**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:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Pass rate**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/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:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Line coverage**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/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:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Branch coverage**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/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.
For more information about SCA reports, see [Quality report types](test-workflow-actions.md#test-reporting).
Corresponding UI:
+ Outputs tab/Reports/Automatically discover reports/Success criteria/**Vulnerabilities**
+ Outputs tab/Reports/Manually configure reports/*report-name-1*/Success criteria/**Vulnerabilities**
## 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](#github.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](#github.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 report/*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
## Steps
(*action-name*/Configuration/**Steps**)
(Required)
Specify your GitHub Action code as it appears on the action's details page in [GitHub Marketplace](https://github.com/marketplace). Add the code following these guidelines:
1. Paste the code from the GitHub Action’s `steps:` section into the `Steps:` section of the CodeCatalyst workflow. The code starts with a dash (-) and looks similar to the following.
GitHub code to paste:
```
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: master
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
1. Review the code you just pasted and modify it as necessary so that it conforms to CodeCatalyst standards. For example, with the preceding code block, you might remove the code in *red italics*, and add the code in **bold**.
CodeCatalyst workflow yaml:
```
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
env:
VALIDATE_ALL_CODEBASE: false
DEFAULT_BRANCH: mastermain
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
1. For additional code that’s included with the GitHub Action but does not exist inside the `steps:` section, add it to the CodeCatalyst workflow using CodeCatalyst-equivalent code. You can review the [Workflow YAML definition](workflow-reference.md) to gain insight into how you might port your GitHub code to CodeCatalyst. Detailed migration steps are outside the scope of this guide.
Here is an example of how to specify file paths in a **GitHub Actions** action:
```
Steps:
- name: Lint Code Base
uses: github/super-linter@v4
...
- run: cd /sources/WorkflowSource/MyFolder/ && cat file.txt
- run: cd /artifacts/MyGitHubAction/MyArtifact/MyFolder/ && cat file2.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/**GitHub Actions YAML**