Artifacts¶

class Artifacts : YamlExport

Configures job artifacts that are attached to the job when it succeeds, fails, or always.

Job artifacts are a list of files and directories that are sent to GitLab after the job finishes. They are available for download in the GitLab UI if the size is smaller than the maximum artifact size. By default, jobs in later stages automatically download all the artifacts created by jobs in earlier stages.

Example¶

val build by job {
    script {
        shell("make build")
    }

    artifacts {
        include("binaries/")
        include(".config")
        expireIn("1 week")
    }
}

External resources¶

Official documentation

Constructors¶

Artifacts¶

constructor()

Functions¶

accessibility¶

fun accessibility(path: String)

Collects accessibility test reports using pa11y to report on the accessibility impact of changes.

GitLab can display the results of one or more accessibility reports in the merge request accessibility widget, helping teams identify and fix accessibility issues.

Example¶

val accessibilityTest by job {
    script {
        shell("pa11y-ci --sitemap http://localhost:3000/sitemap.xml --reporter json > accessibility-report.json")
    }

    artifacts {
        accessibility("accessibility-report.json")
    }
}

External resources¶

annotations¶

fun annotations(path: String)

Collects annotations to attach auxiliary data to a job.

The annotations report is a JSON file with annotation sections that can contain external links and other auxiliary data displayed on the job output page.

Example¶

val deploy by job {
    script {
        shell("./deploy.sh")
        shell("echo '{\"links\": [{\"external_link\": {\"label\": \"Deployment URL\", \"url\": \"https://app.example.com\"}}]}' > annotations.json")
    }

    artifacts {
        annotations("annotations.json")
    }
}

External resources¶

Official documentation

apiFuzzing¶

fun apiFuzzing(path: String)

Collects API fuzzing security test reports.

GitLab can display the results of one or more API fuzzing reports in:

The merge request security widget
The Project Vulnerability report
The pipeline Security tab
The security dashboard

Example¶

val apiFuzzing by job {
    script {
        shell("run-api-fuzzing-tests")
    }

    artifacts {
        apiFuzzing("gl-api-fuzzing-report.json")
    }
}

External resources¶

Official documentation

browserPerformance¶

fun browserPerformance(path: String)

Collects browser performance test reports.

The browser performance report collects Browser Performance Testing metrics as an artifact. This artifact is a JSON file output by the Sitespeed plugin. GitLab can display the results of only one report in the merge request browser performance testing widget.

GitLab cannot display the combined results of multiple browser_performance reports.

Example¶

val performanceTest by job {
    script {
        shell("sitespeed.io --outputFolder sitespeed-results https://example.com")
    }

    artifacts {
        browserPerformance("sitespeed-results/data/performance.json")
    }
}

External resources¶

Official documentation

clusterImageScanning¶

fun clusterImageScanning(path: String)

Collects cluster image scanning security reports.

Example¶

artifacts {
    clusterImageScanning("gl-cluster-image-scanning-report.json")
}

External resources¶

Official documentation

codeQuality¶

fun codeQuality(path: String)

Collects code quality reports to display code quality information in GitLab.

The collected code quality report uploads to GitLab as an artifact with an expiration time of 1 week. GitLab can display the results of one or more reports in:

The merge request code quality widget
The merge request diff annotations
The full report

Example¶

val code-quality by job {
    script {
        shell("sonar-scanner -Dsonar.qualitygate.wait=true")
    }

    artifacts {
        codeQuality("gl-code-quality-report.json")
    }
}

External resources¶

Official documentation

containerScanning¶

fun containerScanning(path: String)

Collects container scanning security reports.

The collected Container Scanning report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in:

The merge request container scanning widget
The pipeline Security tab
The security dashboard
The Project Vulnerability report

Example¶

val containerScan by job {
    script {
        shell("docker run --rm -v /var/run/docker.sock:/var/run/docker.sock registry.gitlab.com/security-products/container-scanning")
    }

    artifacts {
        containerScanning("gl-container-scanning-report.json")
    }
}

External resources¶

Official documentation

coverage¶

fun coverage(format: String, path: String)

Collects code coverage reports in Cobertura or JaCoCo formats.

The coverage report is uploaded to GitLab as an artifact. You can generate multiple JaCoCo or Cobertura reports and include them using wildcards - the results are aggregated in the final coverage report. The results appear in merge request diff annotations.

Coverage reports from child pipelines appear in merge request diff annotations, but the artifacts themselves are not shared with parent pipelines.

Example¶

val test by job {
    script {
        shell("./gradlew test jacocoTestReport")
    }

    artifacts {
        coverage("cobertura", "build/reports/jacoco/test/jacocoTestReport.xml")
    }
}

Example: JaCoCo format with wildcards¶

artifacts {
    coverage("jacoco", "target/site/jacoco/jacoco*.xml")
}

External resources¶

Official documentation

coverageFuzzing¶

fun coverageFuzzing(path: String)

Collects coverage fuzzing security test reports.

The collected coverage fuzzing report uploads to GitLab as an artifact. GitLab can display the results of one or more reports in:

The merge request coverage fuzzing widget
The pipeline Security tab
The Project Vulnerability report
The security dashboard

Example¶

val coverageFuzzing by job {
    script {
        shell("run-coverage-fuzzing-tests")
    }

    artifacts {
        coverageFuzzing("gl-coverage-fuzzing-report.json")
    }
}

External resources¶

Official documentation

cyclonedx¶

fun cyclonedx(vararg path: String)

Collects CycloneDX software bill of materials (SBOM) reports.

This report is a Software Bill of Materials describing the components of a project following the CycloneDX protocol format. You can specify multiple CycloneDX reports using filename patterns, arrays of filenames, or both. Directories are not supported.

Example¶

val sbomGeneration by job {
    script {
        shell("cyclonedx-npm --output-file gl-sbom-npm.cdx.json")
        shell("cyclonedx-bundler --output-file gl-sbom-bundler.cdx.json")
    }

    artifacts {
        cyclonedx("gl-sbom-npm.cdx.json", "gl-sbom-bundler.cdx.json")
    }
}

Example: using filename patterns¶

artifacts {
    cyclonedx("gl-sbom-*.json")
}

External resources¶

Official documentation

dast¶

fun dast(path: String)

Collects Dynamic Application Security Testing (DAST) reports.

Example¶

artifacts {
    dast("gl-dast-report.json")
}

External resources¶

Official documentation

dependencyScanning¶

fun dependencyScanning(path: String)

Collects dependency scanning security reports.

Example¶

artifacts {
    dependencyScanning("gl-dependency-scanning-report.json")
}

External resources¶

Official documentation

dotenv¶

fun dotenv(path: String)

Collects environment variables from a dotenv file to pass to downstream jobs.

The dotenv file should contain key-value pairs in the format KEY=value. These variables become available as CI/CD variables in downstream jobs.

Example¶

val build by job {
    script {
        shell("echo 'BUILD_VERSION=1.2.3' >> build.env")
        shell("echo 'BUILD_URL=https://example.com' >> build.env")
    }

    artifacts {
        dotenv("build.env")
    }
}

val deploy by job {
    script {
        shell("echo 'Deploying version: $BUILD_VERSION'")
        shell("echo 'Build URL: $BUILD_URL'")
    }
    needs(build)
}

External resources¶

Official documentation

exclude¶

fun exclude(path: String)

Prevents files from being added to the artifacts archive.

Paths are relative to the project directory and can use wildcards with glob patterns. You can call this method multiple times to exclude multiple paths.

Example¶

val build by job {
    script {
        shell("make build")
    }

    artifacts {
        include("binaries/")
        exclude("binaries/**/*.o")
         exclude("*.tmp")
     }
 }

External resources¶

Official documentation

expireIn¶

fun expireIn(time: String)

Specifies how long job artifacts are stored before they expire and are deleted.

The expiration time period begins when the artifact is uploaded and stored on GitLab. If no unit is provided, the time is in seconds. Use "never" to prevent expiration.

Example¶

val build by job {
    script {
        shell("make build")
    }

    artifacts {
        include("binaries/")
        expireIn("1 week")
    }
}

Example: various time formats¶

artifacts {
    include("logs/")
    expireIn("3 mins 4 sec")  // or "2 hrs 20 min", "6 mos 1 day", etc.
}

External resources¶

Official documentation

exposeAs¶

fun exposeAs(name: String)

Exposes job artifacts in the merge request UI with a custom display name.

This creates a download link in the merge request UI that displays the specified name. A maximum of 10 job artifacts per merge request can be exposed.

Example¶

val test by job {
    script {
        shell("echo 'test results' > results.txt")
    }

    artifacts {
        include("results.txt")
        exposeAs("Test Results")
    }
}

External resources¶

Official documentation

include¶

fun include(path: String)

Specifies which files to save as job artifacts.

Paths are relative to the project directory and can use wildcards with glob patterns. You can call this method multiple times to include multiple paths.

Example¶

val build by job {
    script {
        shell("make build")
    }

    artifacts {
        include("binaries/")
        include(".config")
        include("*.log")
    }
}

External resources¶

Official documentation

junit¶

fun junit(path: String)

Collects JUnit test reports to display test results in GitLab's UI.

The JUnit report provides detailed information about test execution, including passed, failed, and skipped tests. GitLab displays this information in merge requests and pipeline views.

Example¶

val test by job {
    script {
        shell("./gradlew test")
    }

    artifacts {
        junit("build/test-results/test/TEST-*.xml")
    }
}

Example: Maven project¶

val test by job {
    script {
        shell("mvn test")
    }

    artifacts {
        junit("target/surefire-reports/TEST-*.xml")
    }
}

External resources¶

Official documentation

licenseScanning¶

fun licenseScanning(path: String)

Collects license scanning reports.

Example¶

artifacts {
    licenseScanning("gl-license-scanning-report.json")
}

External resources¶

Official documentation

loadPerformance¶

fun loadPerformance(path: String)

Collects load performance test reports.

Example¶

artifacts {
    loadPerformance("performance.json")
}

External resources¶

Official documentation

metrics¶

fun metrics(path: String)

Collects metrics reports.

Example¶

artifacts {
    metrics("metrics.txt")
}

External resources¶

Official documentation

name¶

fun name(name: String)

Defines the name of the created artifacts archive.

If not defined, the default name is artifacts, which becomes artifacts.zip when downloaded. CI/CD variables are supported in the name.

Example¶

val build by job {
    script {
        shell("make build")
    }

    artifacts {
        include("binaries/")
        name("build-artifacts-${CI_COMMIT_REF_NAME}")
    }
}

External resources¶

Official documentation

requirements¶

fun requirements(path: String)

Collects requirements reports.

Example¶

artifacts {
    requirements("requirements.json")
}

External resources¶

Official documentation

rule¶

fun rule(rule: When)

Specifies when to upload artifacts based on job result.

By default, artifacts are uploaded only when the job succeeds. Use this method to change when artifacts should be uploaded.

Example¶

val test by job {
    script {
        shell("run-tests")
    }

    artifacts {
        include("test-results/")
        rule(When.Always)  // Upload artifacts regardless of job result
    }
}

Example: upload on failure¶

artifacts {
    include("logs/")
    rule(When.OnFailure)  // Only upload when job fails
}

External resources¶

Official documentation

sast¶

fun sast(path: String)

Collects Static Application Security Testing (SAST) reports.

Example¶

artifacts {
    sast("gl-sast-report.json")
}

External resources¶

Official documentation

secretDetection¶

fun secretDetection(path: String)

Collects secret detection security reports.

Example¶

artifacts {
    secretDetection("gl-secret-detection-report.json")
}

External resources¶

Official documentation

terraform¶

fun terraform(path: String)

Collects Terraform plan reports.

Example¶

artifacts {
    terraform("tfplan.json")
}

External resources¶

Official documentation

toYaml¶

open override fun toYaml(): Yaml

Converts this object into a Yaml object.