# Working with custom actions
New content: [Deleting an action version](https://docs.aws.amazon.com/codecatalyst/latest/adk/deleting-action-version.html)

Added a [Deleting an action version](https://docs.aws.amazon.com/codecatalyst/latest/adk/deleting-action-version.html) topic.

Using the CodeCatalyst console, you can view and publish custom actions in CodeCatalyst. Before managing your actions, you can test them by running workflows and viewing the log details of the run. As a verified partner, you can publish to the CodeCatalyst actions catalog to make the actions publicly available, or they can remain local in your project. After publishing, you can make changes and publish the latest versions of your actions. After an action is published, any CodeCatalyst user can use the action in their workflow.

**Topics**
+ [

# Setting up your project on a local machine
](set-up-workspace-local.md)
+ [

# Testing an action
](testing-action.md)
+ [

# Publishing an action
](actions-publishing.md)
+ [

# Publishing a new action version
](actions-update.md)
+ [

# Deleting an action version
](deleting-action-version.md)

# Setting up your project on a local machine


While it's recommended that you create a Dev Environment and build your action within a CodeCatalyst-supported IDE, you can also set up your project and build your action on your local machine. For more information about setting up a Dev Environment, see [Step 1: Set up your project and Dev Environment](getting-started.md#set-up-workspace-first-action).

**To set up your project**

1. Create an empty project in CodeCatalyst.
**Note**  
Before you create a project, you must have the **Space administrator** role, and you must create or join the space where you want to create the project. For more information, see [Creating a space in CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/spaces-create.html).

   1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

   1. Navigate to the space where you want to create a project.

   1. On the space dashboard, choose **Create project**.

   1. Choose **Start from scratch**.

   1. Under **Give a name to your project**, enter the name that you want to assign to your project. The name must be unique within your space.

   1. Choose **Create project**.

1. Create an empty repository in your new project.
**Note**  
Third-party repositories, such as GitHub repositories, aren't supported for developing, testing, and publishing actions. The actions must be developed in a CodeCatalyst repository.

   1. Navigate to your 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**, provide a name for the repository. Repository names must be unique within a project. For more information about the requirements for repository names, see [Quotas for source repositories in CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/source-quotas.html).

      The action name defaults to the repository name, but it can be changed in CodeCatalyst.

   1. (Optional) In **Description**, add a description for the repository that will help other users in the project understand what the repository is used for.

   1. (Optional) Add a `.gitignore` file for the type of code you plan to push. 

   1. Choose **Create**.
**Note**  
CodeCatalyst adds a `README.md` file to your repository when you create it. CodeCatalyst also creates an initial commit for the repository in a default branch named **main**. You can edit or delete the `README.md` file, but you can't change or delete the default branch.

1. Create a new feature branch and clone the remote repository.

   1. In the navigation pane, choose **Code**, choose **Source repositories**, and then choose the empty repository you created.

   1. Choose **Actions**, and then choose **Create branch**.

   1. In the **Branch name** text input field, enter a *`feature-action-name`*.

   1. In the **Create branch from** dropdown menu, ensure **main**, the source branch you're creating the new branch from, is selected. 

   1. Choose **Clone repository** and **Copy** the **HTTPS clone URL** for the remote repository.

   1. Choose **Create token** for a personal access token (PAT) needed to clone the repository.

   1. Choose **Copy** and save the copied PAT for a later step.

   1. From your working terminal, clone the remote repository in a local folder with the following git command:

      ```
      git clone https://[CODECATALYST-USER]@[GIT-ENDPOINT]/v1/[CODECATALYST-SPACE-NAME]/[CODECATALYST-PROJECT-NAME]/[CODECATALYST-REPO-NAME]
             # The url should be available when you visit the repository created.
      ```

      When prompted for a password, paste the copied PAT as the password and enter it in your working terminal.

   1. Change your directory to the repository you cloned:

      ```
      cd [CODECATALYST-PROJECT-NAME]
      ```

   1. Switch to the new branch:

      ```
      git checkout feature-action-name
      ```

After setting up your project, you can continue on to the next step before you can begin developing your action using the CodeCatalyst ADK. For more information, see [Step 2: Install tools and packages](getting-started.md#install-tools-packages).

# Testing an action


Use the following instructions to add unit tests and also test your custom actions in CodeCatalyst workflows.

**Important**  
Currently, only verified partners can test unpublished action versions in workflows.

**Contents**
+ [

## Adding unit tests
](#test-action-locally)
+ [

## Testing actions in workflows
](#test-action-workflows)

## Adding unit tests


The ADK CLI bootstraps actions with an empty unit test using Jest's testing framework. You can use the empty unit test as a starting point to write sophisticated unit tests. The tests are executed when an action is built, and the action build fails if the tests fail or if the test coverage doesn't meet the expected percentage. You can configure the Jest configuration file (`jest.config.js`) generated by the ADK CLI to incorporate test coverage and reporting, as well as other forms of testing.

The following JavaScript example uses the Jest testing framework to define a test for an outgoing webhook action:

```
// @ts-ignore
import * as core from '@aws/codecatalyst/adk-core';
import { expect, test, describe } from '@jest/globals';
import { getHeadersInput } from '../lib/utils/input-util';
import { WEBHOOK_HEADERS_MALFORMED_MESSAGE } from '../lib/constants';

const SAMPLE_INPUT_URL = 'https://hooks.sample.com';
const SAMPLE_INPUT_BODY = '{"Sample": "BODY"}';

describe('Outgoing Webhook Action', () => {
    test('Raises Validation error if webhook headers aren not JSON format', async () => {
        core.getInput = jest.fn().mockImplementation(inputName => {
            switch (inputName) {
                case 'WebhookRequestURL': {
                    return SAMPLE_INPUT_URL;
                }
                case 'WebhookRequestHeaders': {
                    return 'invalidHeaders';
                }
                case 'WebhookRequestBody': {
                    return SAMPLE_INPUT_BODY;
                }
                default: {
                    throw new Error('Unknown input provided');
                }
            }
        });
        expect(() => {
            getHeadersInput();
        }).toThrowError(WEBHOOK_HEADERS_MALFORMED_MESSAGE);
    });
});
```

## Testing actions in workflows


To test your action before publishing as a verified partner, you can run it within the workflow and view the run's details. Your workflow generally runs automatically due to a trigger that can include one or more events, such as a code push or pull request. If a trigger isn't defined in the workflow, the workflow can only be started manually. For more information, see [Creating, editing, and deleting a workflow](https://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-create-edit-delete-workflow.html). 

The ADK generates a continuous integration (CI) workflow that is ready to be used in CodeCatalyst. By default, a bootstrapped action produces a `dist/` folder with an artifact that contains the dependencies the workflow requires to run successfully in CodeCatalyst. You must build the actions locally and push the content of the `dist/` folder to the action's source repository before testing the actions in a workflow.

An action is determined by an action identifier, which consists of the action name and action version. In the workflow definition file, this information indicates which action and version to run in the workflow. When an action is not published, `.` is used as an action identifier in the CI workflow, which is generated by the ADK, while testing. This can help to reference an action that is in the same repository as the workflow file (`.codecatalyst/workflows/actionName-CI-Validation.yml`). 

```
Name: MyAction-CI-Validation
SchemaVersion: "1.0"
Triggers:
  - Type: PullRequest
    Events: [ open, revision ]
    Branches:
      - feature-.*
Actions:
  ValidateMyAction:
    Identifier: .
    Inputs:
      Sources:
        - WorkflowSource
    Configuration:
      WhoToGreet : 'TEST'
      HowToGreet : 'TEST'
```

After making any changes to your source code, build your action locally and push your code again to your CodeCatalyst repository before testing the action in a workflow.

**To build and push action source code and the bundle**

1. Run the following npm commands to build your action:

   ```
   npm install
   ```

   ```
   npm run all
   ```

1. Run the following commands to commit the changes to your remote repository:
**Important**  
Make sure the code you're pushing doesn't contain any sensitive information that you don't want to be shared publicly.

   ```
   git add .
   ```

   ```
   git commit -m "commit message"
   ```

   ```
   git push
   ```

   If you're making changes using a Dev Environment with a supported IDE, you can also use the source control options available in the IDE.

The action can now be tested with the ADK-generated workflow. By default, the workflow's name is `ActionName-CI-Validation`.

**To test an action within a ADK-generated workflow**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to the CodeCatalyst project page.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. From the repository and branch dropdown menus, select the repository and feature branch in which you created the action and its workflow.

1. Choose the workflow you want to test.

1. Choose **Run** to perform the actions defined in the workflow configuration file and get the associated logs, artifacts, and variables.

1. View the workflow run status and details. For more information, see [Viewing workflow run status and details](https://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-view-run.html).

**To test an action in a new workflow**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to the CodeCatalyst project page.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. From the repository and branch dropdown menus, select the repository and feature branch in which you created the action.

1. Choose **Create workflow**, confirm the repository and feature branch in which you created the action, and then choose **Create**.

1. Choose **\$1 Actions**, choose the **Actions** dropdown menu, and then choose **Local** to view your custom action.

1. (Optional) Choose the name of the custom action to view the action's details, including the description, documentation information, YAML preview, and license file.

1. Choose **\$1** to add your custom action to the workflow and configure the workflow to meet your requirements using the YAML editor or the visual editor. For more information, see [Build, test, and deploy with workflows in CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/flows.html).

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, and on the **Commit workflow** dialog box, do the following:

   1. For **Workflow file name**, leave the default name or enter your own.

   1. For **Commit message**, leave the default message or enter your own.

   1. For **Repository** and **Branch**, choose the source repository and branch for the workflow definition file. These fields should be set to the repository and branch that you specified earlier in the **Create workflow** dialog box. You can change the repository and branch now, if you'd like.
**Note**  
After committing your workflow definition file, it cannot be associated with another repository or branch, so make sure to choose them carefully.

   1. Choose **Commit** to commit the workflow definition file.

1. View the workflow run status and details. For more information, see [Viewing workflow run status and details](https://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-view-run.html).

# Publishing an action


In CodeCatalyst, you can publish multiple versions of an action, retrieve action metadata, and manage your actions. You can publish the actions in your local catalog to the CodeCatalyst actions catalog so that other CodeCatalyst users can use them.

**Important**  
Currently, only verified partners can publish actions to the CodeCatalyst actions catalog.

**Important**  
When your action is published to the CodeCatalyst actions catalog, it is available to all CodeCatalyst users, so make sure that you want the action to be publicly available. Other users don't have to be in your space or project to view your published action. The action's source code, including the workflow YAML file and git history, become visible after the action is published.

**Important**  
If the size of the bundle (`dist/index.js`) is more than 10 megabyte (MB), you will not be able to publish the action to the CodeCatalyst actions catalog. The bundle grows to 10 MB or more when an action has many large dependencies.

The action can only published from the default branch of the source repository. If you developed the action on a feature branch, merge your feature branch with the action to the default branch. 

**To merge your feature branch to the default branch**

Create a pull request for other members to review and merge the changes from the feature branch to the default branch. For more information, see [Working with pull requests in Amazon CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/source-pull-requests.html).

After merging the feature branch with the action information to the default branch, the action details can be configured before publishing the action to the CodeCatalyst actions catalog. The following details can be edited:
+ **Action display name** – The name that appears in the **Actions** list and the Amazon CodeCatalyst catalog (after the action is published). This is initially set in the action definition file `action.yml`.
+ **Action name** – The name is derived from the space name and action version to form the action identifier (for example, test-space/nad-test-45tzuy@v1.0.0). In your workflow, the action identifier is used to specify the action. After publishing the action, this name can't be changed. 
+ **Description** – The description that appears for the action in the **Actions** list and the Amazon CodeCatalyst catalog (after the action is published).
+ **Categories** – The catgories that best describe the action. These categories appear when you or other CodeCatalyst users choose the action's name from CodeCatalyst catalog while working with workflows. This category is initially empty, and at least one category is required before you can publish an action.
+ **Support contact** – The email other CodeCatalyst users can reach out to regarding the action you published. This detail is initially empty and not required to publish your action. 
+ **License** – A plain text file that supplies required license information. This file is created when the action is bootstrapped and is stored at the root of action's source repository. 

**To edit action details**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to the CodeCatalyst project page

1. In the navigation pane, choose **CI/CD**, choose **Actions**, and then choose the action you want to publish.

1. Choose **Edit details** to edit the details for your action:

   1. (Optional) In the **Action display name** field, change the action display name.

   1. (Optional) In the **Action name** field, change the action name.
**Note**  
The **Action name** can't be changed after the action is published.

   1. (Optional) In the **Description** field, change the description.

   1. From the **Categories** dropdown list, choose the type of actions that are part of your workflow. This field is initially empty and requires at least one category before you can publish the action.

   1. (Optional) In the **Support contact** field, enter an email.

   1. Choose **Save**

1. (Optional) Edit the license file.

   1. Choose **View license file** to open the file.

   1. Choose **Edit** and make your changes.

   1. Choose **Commit**, add a message in the **Commit message** field, and then choose **Commit**.

After configuring the action details to meet all the requirements to publish, you can choose the action version you want to publish to the Amazon CodeCatalyst actions catalog.

**To publish your custom action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to the CodeCatalyst project page.

1. In the navigation pane, choose **CI/CD**, choose **Actions**, and then choose the action you want to publish.

1. Choose **Publish version** to view the publish version details.

1. Choose the **Commit** dropdown list, and then choose the commit from the default branch you want to publish.
**Note**  
The commit must meet publishing requirements, including a valid action definition, a readme file, a license file, and entry files.

   The **Code quality** section displays the code quality of your results. Not meeting the quality results doesn't block you from publishing the action version. The **Test details** section provides testing and code coverage results. You can add and run unit tests to meet your requirements for the action. For more information, see [Testing an action](testing-action.md).

1. Choose **Publish** to publish the action to the Amazon CodeCatalyst actions catalog. In the **Versions** table, the status of the version displays **Published** once the action version has been successfully published.

Optionally, you can view and test the action version you published to the Amazon CodeCatalyst actions catalog to ensure it works as expected.

**(Optional) To view and use your published action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to the CodeCatalyst project page.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. From the repository and branch dropdown menus, select the repository and feature branch in which you want to test the published action.

1. Choose **Create workflow**, confirm the repository and feature branch in which you want to test the published action, and then choose **Create**.

1. Choose **\$1 Actions**, and then search for your custom action that you published. You can search the name of your action by entering it in the *Search for actions* field.

1. (Optional) Choose the name of the published action to view the action's details, including the description, documentation information, YAML preview, and license file.

1. Add the action to the workflow, choose the visual editor, and then choose the action to view the **Inputs**, **Configuration**, and **Outputs** fields.
**Note**  
The action now contains the identifier (for example, test-space/test-45tzuy@v1.0.0), which is not available for the action when initially created before publishing.

1. Choose **Commit**, and on the **Commit workflow** dialog box, do the following:

   1. For **Workflow file name**, leave the default name or enter your own.

   1. For **Commit message**, leave the default message or enter your own.

   1. For **Repository** and **Branch**, choose the source repository and branch for the workflow definition file. These fields should be set to the repository and branch that you specified earlier in the **Create workflow** dialog box. You can change the repository and branch now, if you'd like.
**Note**  
After committing your workflow definition file, it cannot be associated with another repository or branch, so make sure to choose them carefully.

   1. Choose **Commit** to commit the workflow definition file.

1. View the workflow run status and details. For more information, see [Viewing workflow run status and details](https://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-view-run.html).

# Publishing a new action version


After publishing your initial action version, you can update your action definition and publish a new version to the Amazon CodeCatalyst actions catalog. Unlike publishing an action initially, you can't change the **Action name** when editing details for later versions.

Consider following Semantic Versioning (SemVar) standards when working with updated versions of your actions. SemVar provides a standardized way to assign and increment version numbers for software packages. When dependencies become complex as your system grows and more packages are integrated into a software, a clear and precise way to convey meaning about changes can help other CodeCatalyst users understand the intentions while you make flexible and reliable specifications. For more information, see [Semantic Versioning 2.0.0](https://semver.org/).

The Conventional Commits specification provides a lightweight convention for structing commit messages, which gives you the ability create an explicit commit history and write automateed tools on top of it. This convention fits with SemVar by describing features, fixes, and beaking changes made in commit messages, including guidelines on how commit messages should be structured. For more information, see [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).

**To publish your new action version**

1. Navigate to your project that was cloned in a local folder, and make your changes in your existing `feature-action-name` branch that was created in [Step 1: Set up your project and Dev Environment](getting-started.md#set-up-workspace-first-action). You can also create a new feature branch from your default branch and make changes in the new branch.

1. Build the package locally and push the source code and bundle:

   1. Run the following npm commands to build your action:

      ```
      npm install
      ```

      ```
      npm run all
      ```

   1. Run the following commands to commit the changes to your remote repository:
**Important**  
Make sure the code you're pushing doesn't contain any sensitive information that you don't want to be shared publicly.

      ```
      git add .
      ```

      ```
      git commit -m "commit message"
      ```

      ```
      git push
      ```

      You can also use the source control options available in the IDE you’re using for your Dev Environment.

1. Create a pull request and merge your feature branch to the default branch, and then publish your new action version to the CodeCatalyst actions catalog. For more information, see [Publishing an action](actions-publishing.md).

Optionally, you can view and test the action version you published to the Amazon CodeCatalyst actions catalog to ensure it works as expected.

**(Optional) To view and use your published action**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to the CodeCatalyst project page.

1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.

1. From the repository and branch dropdown menus, select the repository and feature branch in which you want to test the published action.

1. Choose **Create workflow**, confirm the repository and feature branch in which you want to test the published action, and then choose **Create**.

1. Choose **\$1 Actions**, and then search for your custom action that you published. You can search the name of your action by entering it in the *Search for actions* field.

1. (Optional) Choose the name of the published action to view the action's details, including the description, documentation information, YAML preview, and license file.

1. Add the action to the workflow, choose the visual editor, and then choose the action to view and configure the **Inputs**, **Configuration**, and **Outputs** fields.
**Note**  
The published action contains the identifier (for example, test-space/test-45tzuy@v1.0.0), which is not available for the action when initially created and not published.

1. (Optional) Choose **Validate** to validate the workflow's YAML code before committing.

1. Choose **Commit**, and on the **Commit workflow** dialog box, do the following:

   1. For **Workflow file name**, leave the default name or enter your own.

   1. For **Commit message**, leave the default message or enter your own.

   1. For **Repository** and **Branch**, choose the source repository and branch for the workflow definition file. These fields should be set to the repository and branch that you specified earlier in the **Create workflow** dialog box. You can change the repository and branch now, if you'd like.
**Note**  
After committing your workflow definition file, it cannot be associated with another repository or branch, so make sure to choose them carefully.

   1. Choose **Commit** to commit the workflow definition file.

1. View the workflow run status and details. For more information, see [Viewing workflow run status and details](https://docs.aws.amazon.com/codecatalyst/latest/userguide/workflows-view-run.html).

# Deleting an action version
Deleting an action version

Use the following instructions to delete a published version of an action. Deleting a version removes it from the action catalog so that it is no longer available for use in workflows. Any workflows that currently use the deleted version will stop working. 

**Important**  
To avoid disruption to those who are currently using your action in their workflows, only delete an action version if you've reached the version limit, or if the version contains security vulnerabilities or other critical issues that are impossible to solve with a new version.

**To delete an action version**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. Navigate to the CodeCatalyst project page.

1. In the navigation pane, choose **CI/CD**, and then choose **Actions**.

   Your custom actions appear.

1. Choose the name of the action whose version you want to delete.

1. Choose the radio button next to the version.

1. Choose **Delete**.
**Note**  
If there is only one version available, it cannot be deleted.