Artifacts

An artifact in Horde refers to a set of archived files produced by a build process. The archive corresponds to a particular commit in VCS, allowing for searching for artifacts produced between in a particular stream across a range of time, and includes other indexed keys and metadata that can help it to be manipulated by external tools.

Amongst other things, artifacts can be used to store:

Packaged builds
Precompiled editor builds for UnrealGameSync (often referred to as "PCBs")
Intermediate artifacts transferred between agents by BuildGraph
Test results
Logs and traces

Configuration

Settings for artifacts are configured by their artifact type, which are specified at upload time. Artifact types are arbitrary string identifiers (case insensitive alpha-numeric strings, or the characters -, _, .).

Artifact types are customizable, and new types may be added as needed. They must be declared through Horde config files before Horde will allow clients to upload artifacts of that type.

Types may be configured through the artifactTypes property at the global, project, or stream scopes.

Standard Artifact Types

Horde produces certain artifact types by default:

step-output: Output from a build step which can be used by other build steps. These artifacts are produced based on dependencies between steps configured through BuildGraph.
step-saved: Contents of the AutomationTool log folder, harvested from the agent executing a job once it completes. The Horde Agent sets the path to this output folder for jobs via the uebp_LogFolder environment variable (normally Engine/Programs/AutomationTool/Saved/Logs).
step-trace: Telemetry and trace data for a build step, harvested from the directory given by the UE_TELEMETRY_DIR environment variable (normally Engine/Programs/AutomationTool/Saved/Telemetry). AutomationTool and UnrealBuildTool write timing information for their execution to this folder using the in JSON format, which are replicated to the configured telemetry provider.
step-testdata: Data written to the directory given by the UE_TESTDATA_DIR environment variable by a build step (normally Engine/Programs/AutomationTool/Saved/TestData). Json files in this directory will also be harvested for test data results and surfaced to Automation Hub.

Expiration

Artifacts may be expired automatically using the following settings:

KeepCount: Retains the most recent N artifacts of a particular type in each stream.
KeepDays: Retains each artifact for N days.

If both settings are specified, the artifact will be retained until neither retention policy applies.

If the configuration for an artifact is removed from Horde - because a stream is deleted, for example - any orphanned artifacts will be expired according to the last configured settings.

Uploading Artifacts

Artifacts can be produced by build processes using the CreateArtifact BuildGraph task within a node, or using the Artifact element to indicate that a produced tag should be published as an artifact.

Artifacts produced by build jobs will be listed at the top of the dashboard page for that job.

An example of using the CreateArtifact task can be found in the Engine/Build/InstalledEngineBuild.xml script, which uploads the complete installed build as an installed-build artifact type:

<Node Name="Upload To Horde Win64" Requires="Make Installed Build Win64">
    <CreateArtifact
        Name="installed-build-win64"
        Type="installed-build"
        Description="Installed Build (Windows)"
        BaseDir="$(LocalInstalledDir)"
        Files="..."/>
</Node>

An example of using the Artifact element can be found in the Engine/Build/Graph/Examples/BuildEditorAndTools.xml script, which uploads a set of files as a ugs-pcb artifact type. UnrealGameSync searches for this artifact type to determine which archives are available, along with their associated project and archive type.

<Artifact
    Name="editor"
    Description="Editor PCBs"
    Type="ugs-pcb"
    BasePath="$(ArchiveStagingRelativeDir)"
    Keys="$(UgsProjectKey)"
    Metadata="ArchiveType=Editor"
    Tag="#PublishBinaries"/>

Artifacts may also be uploaded programmatically using the EpicGames.Horde library.

Downloading Artifacts

The easiest way to download an artifact is via the Horde dashboard. While convenient, downloading a zip file directly from the dashboard can be slow and inefficient due to the work the server has to do to re-pack data in that format.

To download artifacts in their native format - which is typically much faster and more efficient - the following methods are available:

UnrealGameSync: The Horde dashboard allows downloading an artifact as a .uartifact file; a JSON file containing metadata about an artifact. Double-clicking on these files will open them in UnrealGameSync and allow downloading them to a local folder.

Command line: The Horde command line tool allows downloading artifacts to an output folder using the following syntax:

horde artifact download -Id=12345678abcd12345678abcd -OutputDir=C:\Folder

Artifacts can be enumerated using the artifact find command:

horde artifact find -streamid=ue5-main -type=step-saved -jobid=670fce208961cf36f3855ff0 -stepid=4994

Programmatically: The EpicGames.Horde library provides interfaces for enumerating and downloading artifacts programmatically. The Horde command-line tool serves as an example for using this API to query artifacts.

The RetrieveArtifact task can be used to find and download artifacts from a build script. By default, the task will search for an artifact in the current stream, at the current changelist - though the Stream and Commit attributes can be used to choose a different source.

<RetrieveArtifact
    Name="build-name"
    Type="installed-build"
    OutputDir="My/Output/Dir" />

Additionally, specifying the MaxCommit parameter will find the most recent artifact at or before the given change.

Keys & Metadata

Artifacts are designed to be consumed programmatically and include various metadata fields allowing them to be manipulated in a standard way, such as a name, type, stream, and commit identifier.

Artifacts also support user-defined keys and metadata. Both are arbitrary strings attached to an artifact, with the difference that keys are globally indexed and support searching, and metadata is not.

All artifacts uploaded by a particular job will automatically have job:12345678abcd12345678abcd and job:12345678abcd12345678abcd/step:abcd keys added to them.

6.8 KiB Raw Blame History