Introduction
Understanding organizationsUnderstanding componentsManage organizationsManage componentsManage component Jira integrations
Set up your first organizationUnderstanding users and teamsUnderstanding role-based access controlManage usersManage teamsConfigure role-based access controlRBAC permissions reference
Understanding authentication in CloudBees UnifySet up multifactor authenticationConfigure SAML single sign-onConfigure OIDC authenticationConfigure network security policiesNetwork security reference
Understanding platform configurationUnderstanding environmentsManage properties and secretsManage environmentsTrack environment inventoryConfigure containersSet up preconfigured actionsConfigure notifications
Accessibility policy referenceShared responsibility model referenceSubscription and services agreementSupport policiesSupported browsers and external tools
Introduction
Understanding feature managementUnderstanding Configuration as CodeGet started with feature managementCreate and manage feature flagsConfigure feature flag targetingOrganize feature flagsImplement feature flag governanceConfiguration as Code reference
Understanding flag impressions and activity statusUnderstanding flag healthUnderstanding code referencesReview and clean up feature flagsSet up code references
Understanding Jira integration for feature flagsSet up the Jira integrationLink Jira tickets to feature flags
Understanding multiple SDK keysBuild your first mobile app with feature flagsBuild your first feature-flagged web applicationBuild your first feature-flagged backend serviceInstall client-side SDKsInstall server-side SDKsConfigure multiple SDK keysMobile SDK referenceWeb SDK referenceBackend SDK referenceClient SDK referenceFlag implementation reference
Introduction
Understanding CI workflowsCreate a build workflowCreate and manage workflowsCreate reusable workflowsTest and validate containers in workflowsCheck out source codeTrigger workflows remotelyWorkflow syntax referenceJobs syntax referenceSteps syntax referenceServices syntax reference
Monitor workflow runsView test results in runsView evidence in runsView deployments in runsManage workflow artifactsPublish test resultsPublish evidence itemsGenerate a software bill of materialsManage ServiceNow change requests
Configure workflow credentialsConfigure AWS credentialsConfigure container registry credentialsConfigure Git credentialsIntegrate external secret providers
Understanding GitHub Actions integrationSet up GitHub Actions integrationDisplay GitHub Actions workflows and runsRegister GHA build artifactsPublish GHA deployed artifactsPublish GHA test resultsPublish GHA evidence itemsTrigger CloudBees workflows from GitHub ActionsScan with GitHub Actions
Understanding CloudBees CI and Jenkins® integrationConnect CI and Jenkins controllersMonitor CI and Jenkins buildsRegister CI build artifactsRegister CI deployed artifactsPublish CI test resultsConfigure CI security scanningCI and Jenkins integration reference
Build and publish container imagesUnderstanding external CI/CD integrationsRun external CI/CD jobsExternal CI/CD action reference
Introduction
Understanding release orchestrationManage applicationsCreate deployer workflowsCreate staged workflowsCreate and manage releasesOrchestrate multi-workflow releasesRelease management reference
Understanding artifact managementRegister and track artifactsStore and retrieve artifactsPromote artifactsGenerate a software bill of materialsArtifact management reference
Deploy with HelmDeploy to KubernetesContainer deployment reference
Deploy to AWSAWS deployment reference
Deploy with enterprise platformsExecute remote deployment commandsEnterprise deployment reference
Verify deployments with New RelicDeployment verification reference

Manage workflow artifacts

9 minute read

Artifacts are the output of a software development process, such as binary build and configuration files, and are often stored in a cloud storage service. You can download artifacts from storage and use them in subsequent testing or deploy steps in a development pipeline.

Versioning of an artifact enables the management of artifacts effectively, providing the following:

  • Traceability: Connect an artifact to the specific workflow run where it was created.

  • Reusability: Reuse artifacts with consistency across environments and deployments.

  • Reliability and compliance: Link artifacts to evidence such as image digests or chart names.

Prerequisites for artifact traceability

To enable artifact traceability, the artifact information must be registered to the CloudBees Unify.

If using a CloudBees Unify workflow, do one of the following to save artifact information:

Register artifacts from CI/Jenkins pipelines

Register any outputs of your integrated CI pipeline build workflow run, such as compiled binaries and log files, to CloudBees Unify.

To register artifacts from your CI build to CloudBees Unify:

  1. Complete the integration setup for your CI system.

  2. Specify a registerBuildArtifactMetadata step in your Jenkinsfile that contains the required inputs listed in the table below:

    Table 1. Input details
    Input name Data type Required? Description

    name

    String

    Yes

    The name of the artifact reported to CloudBees Unify.

    url

    String

    Yes

    The URL where the artifact version is located. For example, docker.io/myapp/myimg:1.0.0.

    version

    String

    Yes

    The version of the artifact to send to CloudBees Unify for artifact traceability purposes.

    digest

    String

    No

    The hash or checksum that uniquely identifies the artifact version.

    CloudBees recommends specifying the digest to track artifact versions across repositories. For more information, refer to Artifact deployment and publish history.

    label

    String

    No

    A comma-separated list of artifact labels.

    type

    String

    No

    The type of artifact, such as Docker or Maven.

    componentId

    String

    No

    The ID of the component associated with the artifact. If not provided, the default value is the component ID where the CloudBees CI / Jenkins workflow is located.

    commit

    String

    Only required if a different repository/branch.[1]

    The commit used to build the artifact. The default value is the commit hash from the CloudBees CI / Jenkins build.

    commitUrl

    String

    Only required if a different repository/branch.[1]

    The URL of the commit used to build the artifact. The default value is the commit URL from the CloudBees CI / Jenkins build.

    repositoryUrl

    String

    Only required if a different repository/branch.[1]

    The URL of the repository. The default value is the repository URL from the CloudBees CI / Jenkins build.

    ref

    String

    Only required if a different repository/branch.[1]

    The branch or tag ref used to build the artifact. The default value is the ref from the CloudBees CI / Jenkins build.

    [1] By default, the artifact version is associated with the code commit from the CI build. If a different commit/repository/branch has been checked out for building the artifact, specify those commit details instead. If you do not want to associate commit details with this artifact version, omit this parameter.

Usage examples

The following is a basic example of using the registerBuildArtifactMetadata step with only the required parameters:

pipeline {
    agent any

    stages {
        stage('Registering build artifact') {
            steps {
                echo 'Registering the metadata'
                registerBuildArtifactMetadata(
                    name: "my-artifact",
                    url: "https://my-artifact-url.com",
                    version: "1.0.0"
                )
            }
        }
    }
}
▼

The following example specifies optional parameters:

pipeline {
    agent any

    stages {
        stage('Registering build artifact') {
            steps {
                echo 'Registering the metadata'
                registerBuildArtifactMetadata(
                    name: "my-Docker-artifact",
                    url: "https://hub.docker.com/repository/docker/example",
                    version: "1.0.0",
                    digest: "sha256:abcdef1234567890",
                    label: "staging,prod",
                    type: "Docker",
                    componentId: "e04f06b0-992c-4267-b133-91092b252845",
                    commit: "1234abcd-ab34-123cd-56ef-12345678abcd",
                    commitUrl: "https://github.com/example/repo/commit/1234abcd-ab34-123cd-56ef-12345678abcd",
                    repositoryUrl: "https://github.com/example/repo",
                    ref: "refs/heads/main"
                )
            }
        }
    }
}
▼

Access and view artifacts

Use Artifacts to access information generated by workflow runs.

Access artifacts using one of the following options:

Option 1: Component associated with a workflow run producing artifacts.

  1. Select Components.

  2. Find and select a Component that has a workflow run producing a build artifact.

  3. Select Runs.

  4. Then select Run details > Build artifacts. The following information displays:

    • Artifact name

    • Artifact version

    • A link to the artifact digest

    • A link to the artifact location

Option 2: Artifacts associated with a component or application.

  1. Select Components.

  2. Find and select a Component that has a workflow run producing an artifact.

  3. Select Components  Artifacts to view associated artifacts.

    • In addition to the information available in Build artifacts, the following displays:

Option 3: Artifacts associated with an application release.

  1. Select Applications.

  2. Find and select an Application that has a release that includes an artifact.

  3. Select Applications  Releases, and then select a release Name.

  4. Select an Artifact to display the Components  Artifacts view described above.

Option 4: Artifacts from a specific workflow run.

  1. Select Up/down arrows, and then select an organization or component.

  2. Select Runs and then select a run by its Name.

  3. Select Runs:  Build artifacts to display the list of artifacts generated by the run.

    The artifacts associated with the run are displayed accordingly.

Each artifact entry in Build artifacts displays the following options:

For CI/Jenkins integrated builds, you can also access the build details directly and select Build artifacts to list only the artifacts generated during that specific CI build. For integrated CI components, all artifacts are also available in the component’s Artifacts tab.

(Optional) Filter and search for artifact versions:

The filter and search features are only available after accessing the selected artifact from Components  Artifacts or Applications  Releases.

  • Search for a specific artifact by entering all or part of its name into the Search field.

  • Select Filter to narrow the search for only those artifacts with specific names and/or labels.

  • Use the toggle Toggled on to display the full version history. The default display Toggled off shows only the latest artifact versions.

    Artifact version information might not display while generation is in progress.

The artifacts built or deployed by a workflow run in that component or application are displayed.

Explore the artifact list using the following options:

  • Select Create version to Create artifact versions manually.

  • Toggle between the latest artifact version and full version history:

    • Toggled off displays only the latest artifact versions (default view).

    • Toggled on displays the full version history.

  • Select the Jira icon to view the list of work items associated with the artifact version.

    • The list opens in a side panel, and displays the issue keys, summary, and status. Select an issue key to open the issue in Jira.

  • Add, edit, or remove Manage artifact labels.

    • Filtering the list by labels is also an option.

  • Select Copy to copy the digest or location path.

  • Select a run link to display details of the run that published the artifact.

  • Select View deployment history to display an artifact’s Track deployment and publish history.

Create artifact versions manually

Creating an artifact version enables effective management of software artifacts by:

  • Keeping track of specific artifact versions linked to a workflow run.

  • Maintaining observability for compliance reasons.

  • Managing dependencies effectively.

  • Automatically deploying newer versions of artifacts to different environments as part of automated workflows.

To create an artifact version:

  1. Select Components, and then select a Component.

  2. Select Components  Artifacts.

  3. Select Create version.

  4. Enter a Name for the artifact.

    You can include the path for the artifact in the name.

  5. Enter the version.

  6. Enter the URL location of the artifact version.

  7. (Optional) Enter the Job URL; the URL of the workflow run that has built the artifact version.

  8. (Optional) Enter the Digest; the signature of the artifact version binary (usually provided by the host repository).

  9. Select Save. The artifact version is created.

Manage artifact labels

Create custom labels for artifact versions, and use them to organize and filter the artifacts listed in a component. Text strings are an acceptable label, and labels are reusable. Multiple labels can be added to an artifact version.

Artifact labels are useful for organizing artifact versions into groupings such as:

  • User or team

  • Release or testing status

  • Environment

  • Version

For example, use "Testing" and "Dev team" labels on an artifact in the development stage, and a "For release" label on all artifacts ready for production release. In the UI, filter the artifact list by the "For release" label, to get a convenient view of all artifacts ready for release.

If multiple labels for an artifact version have been created, only one is displayed by default in the artifact list.

  • The link displays the number of additional labels not displayed.

  • Select more to display all the custom labels for an artifact version.

Create or add artifact labels in the UI

Create custom labels for an artifact version, and/or add existing labels. An artifact version may have multiple labels.

A maximum of 20 labels are allowed per artifact version, with a maximum of 20 characters per label.

To create or add an artifact version label:

  1. Go to Components  Artifacts.

  2. Select the link next to the artifact version to label. The link varies according to the label status:

    • Add label Add (an unlabeled artifact)

    • Edit (an artifact with a single label)

    • +n more (an artifact with two or more labels)

  3. Select Labels, and then use either of the following methods:

    • Enter a custom label, and then select Create "<custom label name>", where <custom label name> is the label name.

    • Select an existing label from the options to highlight it (not shown).

      Scroll down to display all the options in the label list.

    • (Optional) Add or create more labels using the above methods.

  4. Select Save. The artifact version is labeled.

Remove artifact labels in the UI

Remove label(s) from an artifact version. Do the following:

  1. Navigate to Components  Artifacts.

  2. Select either:

    • Edit, if the artifact has one label.

    • +n more, if the artifact has two or more labels.

  3. Select Labels to display the labels list, and remove a label by doing one of the following:

    • Deselect the highlighted label in the label options.

    • Select next to the label.

  4. Select Save when all desired labels have been removed. The label(s) are removed from the artifact version.

    Once a label has been removed from all artifact versions, it is deleted from CloudBees Unify.

Manage labels using workflow actions

The artifact ID is a unique identifier of an artifact version; this ID is used in actions to manage labels in workflow runs.

Apply the appropriate action based on the type of workflow being run:

Table 2. Action to use based on workflow type
If your workflow is: Manage labels with:

CloudBees Unify workflow

CloudBees Unify action to manage artifact version labels

GitHub Actions (GHA) workflow

GHA to manage artifact version labels

Track deployment and publish history

The deployment and publish history provides an information timeline for each artifact digest. The history can track an artifact across repositories using the digest, which serves as a unique digital signature for the artifact binary. In that case, the artifact name and version can be different.

To collect artifact deployment data, a workflow must contain an operation to publish an artifact.

To access the history:

  1. Select Components, and then select a Component.

  2. Select Components  Artifacts to display the artifact list.

  3. Select History for an artifact version. The artifact history is displayed.

The artifact version history displays the following information:

  1. Select History to copy the digest.

  2. Each deployment or publishing event is specified and includes the:

    • Event timestamp

    • Event type: Deployed or Published

    • Artifact name

    • Artifact version number

    • Environment name, if applicable

    • Repository URL

    • Workflow run: Includes a link to the run details of the workflow that deployed the artifact.

A message displays if no digest or history is available for the artifact.

Add or remove work items associated with an artifact version

Manage work items associated with an artifact version to track work related to that artifact version.

Add work items to an artifact version

To add work items to an artifact version:

  1. Navigate to the appropriate Component artifact list.

  2. Select Add for the artifact version to add work items to. The Work items side panel opens.

  3. Enter the work item ID in the Search field.

  4. Select Link to link the work item to the artifact version.

    Refresh CloudBees Unify to verify the work item was successfully linked to the artifact version.

  5. Select Add work item to add more work items, or select Close or X to close the side panel.

Remove work items associated with an artifact version

To remove work items from an artifact version:

  1. Navigate to the appropriate Component artifact list.

  2. Select the Jira icon for the artifact version to remove associated work items.

    The Work items side panel opens and lists the work items currently linked to the artifact version.

  3. Select Delete for the work item to remove. A confirmation message appears.

  4. Select Delete to confirm.

    Refresh CloudBees Unify to verify the work item was successfully removed from the artifact version.

    Removing a work item from an artifact version does not delete the work item in Jira.

  5. Select Close or X to close the side panel.

Delete artifact versions

To reduce clutter in your organization, delete artifact versions. Delete multiple versions at once using the bulk delete feature.

To delete artifact versions:

  1. Select Components, and then select a Component.

  2. Select Components  Artifacts.

  3. (Optional) Select Display full version history to Display full version history.

  4. (Optional) Use Search or Filters to refine the artifact version list.

  5. Do one of the following:

    1. Select the Checked box of each artifact version to delete.

    2. Select the Checked box in the heading row to select all versions (bulk delete).

  6. Select Delete. A delete confirmation message displays.

  7. Select Delete artifact versions to confirm. The selected artifact version(s) are deleted.

Bulk delete versions
Figure 1. Bulk delete artifact versions
View deployments in runs
Publish test results