Working with artifacts - Amazon CodeCatalyst
Defining an output artifactDefining an input artifactReferencing files in an artifactDownloading artifactsExamples

Working with artifacts

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.

Defining an output artifact

Use the following instructions to define an artifact that you want an 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/.

  2. Choose your project.

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

  4. 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.

  5. Choose Edit.

  6. Choose Visual.

  7. In the workflow diagram, choose the action that will produce the artifact.

  8. Choose the Outputs tab.

  9. Under Artifacts, choose Add artifact.

  10. 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 (_). 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 Working with artifacts.

    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.

    For more information about artifacts, including examples, see Working with artifacts.

    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 files in a source repository and Referencing files in an artifact.

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

  12. 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/.

  2. Choose your project.

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

  4. 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.

  5. Choose Edit.

  6. Choose YAML.

  7. 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. For more information, see the Workflow definition reference for your action.

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

  9. Choose Commit, enter a commit message, and choose Commit again.

Defining an input artifact

If you want to use an artifact generated by another 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 definition reference 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. 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/.

  2. Choose your project.

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

  4. 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.

  5. Choose Edit.

  6. Choose Visual.

  7. In the workflow diagram, choose the action where you want to specify an artifact as input.

  8. Choose Inputs.

  9. 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 Working with artifacts.

    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.

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

  11. 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/.

  2. Choose your project.

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

  4. 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.

  5. Choose Edit.

  6. Choose YAML.

  7. 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.

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

  9. 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 workflow actions, complete the following procedure.

Note

See also Referencing files in a source repository.

To reference files in an artifact

  • 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:
      Steps:
        - run: cd $CATALYST_SOURCE_DIR_artifact-name/build-output && cat file.txt

    In the previous code, the action looks in the build-output directory in the artifact-name artifact to find and display the file.txt file.

    For more examples, see Examples.

    Note

    You may be able to omit $CATALYST_SOURCE_DIR_artifact-name/ prefix depending on how you've configured your action. For more information, see the following guidance.

    Guidance on how to refer to variables:

    • If your action includes only one item under Inputs (for example, it includes one input artifact and no source), then you can omit the prefix and specify just the file path relative to the artifact root.

    • You can also omit the prefix if the file resides in the primary input. The primary input is either the WorkflowSource, or the first input artifact listed, if there is no WorkflowSource.

    • The prefix can be different depending on the action you're using. For more information, see the following table.

Action type File path prefix to use Example

Build action, test action

$CATALYST_SOURCE_DIR_artifact-name/

$CATALYST_SOURCE_DIR_MyArtifact/folder1/file.txt

All other actions

$CATALYST_SOURCE_DIR_artifact-name/

or

/artifacts/current-action-name/artifact-name/ (this path is a symbolic link to $CATALYST_SOURCE_DIR_artifact-name/)

$CATALYST_SOURCE_DIR_MyArtifact/folder1/file.txt

or

/artifacts/MyCurrentAction/MyArtifact/folder1/file.txt

Downloading artifacts

You can download and inspect artifacts generated by your 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/.

  2. Choose your project.

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

  4. 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.

  5. AUnder the workflow's name, choose Runs.

  6. In Run history, in the Run ID column, choose a run. For example, Run-95a4d.

  7. Under the run's name, choose Artifacts.

  8. Next to an artifact, choose Download. An archive file downloads. Its file name consists of seven random characters.

  9. Extract the archive using an archive extraction utility of your choice.

Examples

The following examples show how to output and reference artifacts in the workflow definition file.

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.

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. 

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. This is because there is only one item specified under Inputs.

Note

For more information on referencing files, see Referencing files in an artifact.

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. 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.

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