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.
Topics
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.
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.
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.txtIn the previous code, the action looks in the
build-output
directory in theartifact-name
artifact to find and display thefile.txt
file.For more examples, see Examples.
Note
You may be able to omit
$CATALYST_SOURCE_DIR_
prefix depending on how you've configured your action. For more information, see the following guidance.artifact-name
/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 noWorkflowSource
. -
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 |
---|---|---|
|
|
|
All other actions |
or
|
or
|
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
Open the CodeCatalyst console at https://codecatalyst.aws/
. -
Choose your project.
In the navigation pane, choose CI/CD, and then choose Workflows.
-
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.
-
AUnder the workflow's name, choose Runs.
-
In Run history, in the Run ID column, choose a run. For example,
Run-95a4d
. -
Under the run's name, choose Artifacts.
-
Next to an artifact, choose Download. An archive file downloads. Its file name consists of seven random characters.
-
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.
Topics
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