This is Beta Software. Finished releases are published directly to svn:dist/release.

5.1.2. Checks

Up: 5.1. Compose phase

Prev: 5.1.1. Uploading files

Next: 5.1.3. License checks

Sections:

Overview

ATR runs automated checks on release artifacts so that you can validate compliance and completeness before a vote. The checks focus on signatures, hashes, archive layout, licensing, and software bill of materials (SBOM) content. This document explains what ATR checks, when those checks run, and how to interpret results.

Checks are recorded against the release revision that you upload, and the results remain visible to reviewers and voters. The checks run in the background and appear in the checks view for the revision as they complete.

How ATR selects checks

ATR chooses checks for each new draft revision based on file names and project policy:

  • .asc files: signature verification.
  • .sha256 and .sha512 files: checksum verification.
  • .tar.gz, .tgz and .zip archives: archive structure and license checks.
  • CycloneDX JSON SBOMs, such as .cdx.json files: SBOM analysis.

ATR also checks file names and required signatures and checksums across the revision.

Project policy identifies source and binary artifacts and sets exclusions for license checks. For source artifacts, you can choose lightweight license checks, Apache RAT, or both. Binary artifacts always use the lightweight checks.

Understanding check results

Each check result has a status of note, suggestion, concern, blocker, or exception. A note indicates that the check ran and has nothing substantial to report. A suggestion indicates a structural or recommendation difference that release managers may consider but is not a policy violation. A concern indicates that ATR could not be certain about a condition and the release manager must investigate. A blocker indicates that a mandatory policy condition was violated and the release cannot proceed. An exception indicates that the check could not complete due to some unexpected internal ATR error.

Each check section below names the exact checker key that ATR records for that check. If you would like checks to change for all projects, you can file an ATR issue.

Individual checks

Path and naming checks

ATR validates the file layout of the revision against ASF release rules. For each artifact it expects a matching signature file with the .asc suffix and at least one checksum file with the .sha256 or .sha512 suffix. It verifies that metadata files correspond to an existing artifact and warns when a metadata suffix is recommended against by policy. It rejects .md5 checksums and .sig signature files and warns about .sha1 and .sha. It rejects dotfiles except for those under the .atr directory, and it rejects a KEYS file inside the artifact bundle because keys are managed through the keys section. If the project is a podling, it requires the word "incubating" in artifact filenames.

This check records separate checker keys for concerns, suggestions, and notes. It uses atr.tasks.checks.paths.check_errors for concerns, atr.tasks.checks.paths.check_warnings for suggestions, and atr.tasks.checks.paths.check_success for notes. The requirement that a release contains at least one source artifact is recorded under atr.tasks.checks.paths.check_source.

Hash verification

For each .sha256 or .sha512 file, ATR computes the hash of the referenced artifact and compares it with the expected value. It supports files that contain just the hash as well as files that include a filename and hash on the same line. If the suffix does not indicate sha256 or sha512, the check fails.

The checker key is atr.tasks.checks.file_hash.check.

Signature verification

For each .asc signature file, ATR verifies the signature against the matching artifact using the public keys stored for the release committee. The signature is accepted only when it verifies and when the signing key is associated with an ASF UID or is the committee's automated release signing key, with a primary UID containing "Automated Release Signing" or "Services RM" (ignoring case) and the email address private@[committee name].apache.org. If no suitable key is found or the signature does not match the artifact, the check fails.

The key which made the signature, which may be a subkey, must also meet the minimum strength for signing releases. ATR records a blocker when a signature was made by a DSA key of any size, or by an RSA key shorter than 2048 bits, even if the signature itself verifies. See Required key settings for the full list.

ATR also raises a concern when the ASF UID of the signing key is not one of the ASF UIDs recorded as having uploaded the artifact, because an artifact is expected to be signed by the person who uploaded it. The automated release signing key is exempt. The concern does not block a vote, but it must be acknowledged before one is started.

The checker key is atr.tasks.checks.signature.check, and the uploader concern is recorded under atr.tasks.checks.signature.check_uploader_mismatch.

Archive integrity checks

ATR validates new archives in supported formats before creating a revision. If an archive is corrupt or exceeds the extraction limits, the upload fails and the error appears on the compose page. See Archive validation for what happens while an upload is checked and how to retry a failed upload.

Archive structure checks

ATR expects each archive to contain exactly one root directory. The expected root name is derived from the archive filename base, without extension. When the archive filename base ends with the suffix source or src, ATR accepts a root directory that either includes that suffix or omits it. When the archive filename base has no such suffix, the root directory must match the base. If the root does not match, ATR records a concern so that you can review project conventions. Structure checks are skipped for artifacts that are classified as binary by project policy.

ATR also recognizes npm pack archives. When the root directory is named package, ATR looks for a file named package.json and validates that it contains a name and version. If the file is present and valid, ATR treats this layout as acceptable. If the package name and version do not match the archive filename base, ATR records a concern.

The checker key for tar based structure checks is atr.tasks.checks.targz.structure. The checker key for zip structure checks is atr.tasks.checks.zipformat.structure.

License files in archives

ATR checks for LICENSE and NOTICE files at the top level of the root directory each archive. It requires exactly one of each. The LICENSE content must match the Apache License text with only whitespace differences, though https may be used in place of http for Apache license URLs. The NOTICE file must be valid UTF-8 text and must include a product line, an ASF copyright statement, and the standard ASF attribution line. For podling projects ATR also requires a DISCLAIMER or DISCLAIMER-WIP file at the same level. These lightweight license checks can run for both source and binary archives but if your project selects Apache RAT only for source artifacts, the lightweight checks are skipped for source archives. They still run for binary archives.

The checker key is atr.tasks.checks.license.files.

You can read more about license checks.

License headers in source files

ATR performs a lightweight scan of source files inside each archive to verify Apache License headers. It inspects the first four kilobytes of each file with a recognized source file suffix and checks for the standard Apache License header text or the three-field SPDX form. Files with generated file suffixes such as .bundle.js, .chunk.js, .css.map, .js.map, .min.css, .min.js, and .min.map are treated as generated and are skipped. Files that include generated markers such as Generated By JJTree or Generated By JavaCC are always accepted as valid. If you configure lightweight exclusions in your project policy, those patterns are also skipped for source artifacts.

The checker key is atr.tasks.checks.license.headers.

You can read more about license checks.

Apache RAT license scan

ATR can run Apache RAT on source archives unless your project policy selects lightweight mode only. RAT runs in a temporary extraction directory, uses standard exclusions for common SCM and IDE files, and always excludes known generated file patterns. If the archive includes a RAT excludes file with the standard name .rat-excludes, ATR uses it as the exclusion file and sets the scan root to the directory that contains it. ATR records a concern if more than one such file is present or if files exist outside that scan root. If no such file exists, ATR can apply project policy RAT exclusions and an extended set of standard exclusions. The check records concerns for unapproved or unknown licenses, and records per file results for those files. RAT does not run for binary artifacts, even if those files are packaged in an archive format that otherwise triggers license checks.

The checker key is atr.tasks.checks.rat.check.

You can read more about license checks.

SBOM checks

ATR recognizes CycloneDX SBOM files with the .cdx.json suffix. When you upload such a file, ATR runs a special scoring tool check that evaluates NTIA 2021 conformance, CycloneDX validation results, license signals, and vulnerability data derived from the SBOM. If a previous release exists, ATR compares current and prior license and vulnerability information and records that context with the result. ATR also provides additional SBOM tasks that you can run from the interface: you can ask ATR to generate a CycloneDX SBOM from an archive using the syft tool, to score a SBOM using SBOM QS, to augment an existing SBOM with NTIA properties, or to run an OSV vulnerability scan that updates the SBOM. These tasks may create a new revision because the SBOM file is updated with new content.

SBOM tasks record task results rather than check results, so there is no checker key to use in ignore rules for SBOM tasks. The results are presented separately from regular checks, on their own page.

Check caching and reruns

To save time, ATR caches check results based on a hash of the check inputs, and will therefore sometimes reuse results from a prior run if the file is identical.

For debugging only, an admin can force a cache bust by clicking the "Disable global cache" button in the compose phase, which will add a release-specific suffix to the cache key, forcing a re-run.

Project policy inputs

Several project and committee settings influence which checks run, what they skip, and how their results are interpreted. This section lists each setting that can change the outcome of a check, where to find it, and what it does. Most of these settings live on the project settings page in the Release policy - Compose options form. Committee signing keys are managed separately.

Source and binary artifact paths

You can configure path patterns that tell ATR which of your artifacts are source artifacts and which are binary. These are the Source artifact paths and Binary artifact paths fields in the compose options form, and they accept one .gitignore style pattern per line. ATR uses these patterns to classify each file, and the classification makes several checks behave differently depending on whether an artifact is source or binary: archive structure checks are skipped for binary artifacts, RAT checks never runs on binary artifacts, and source tree comparisons only run for source artifacts.

Please note that there is currently a bug where license file exclusions are not applied when a source archive is not explicitly classified through release policy options.

License check mode

The Source artifact license checker setting controls which license checks run on source archives. You can set it to Both (the default), Lightweight, or RAT. Binary artifacts always use the lightweight checks regardless of this setting, because RAT does not operate on binary artifacts. In Lightweight mode, therefore, the RAT check is skipped entirely. In RAT mode, the lightweight checks are skipped for source artifacts only.

You can read more about license checks.

License check exclusions

Two separate sets of exclusion patterns let you skip files during license scanning. The RAT source excludes are applied when RAT scans a source artifact that does not contain its own .rat-excludes file. The Lightweight source excludes are always applied during the lightweight license header scan for source artifacts. In both cases the exclusions only take effect for artifacts that are classified as source by the source artifact paths setting (this is a bug).

If you would rather not maintain the RAT excludes here as well as in your project, set a RAT excludes URL pointing at a .rat-excludes file your project already keeps in git. We fetch it fresh for each revision we check, and record what we used against the revision. The URL must be on an apache.org host or raw.githubusercontent.com. When a source artifact ships its own .rat-excludes that still wins, then the URL, then the RAT source excludes typed above.

You can read more about license check exclusions.

Committee signing keys

Signature verification depends on the public signing keys registered for the project's committee. ATR verifies each .asc signature against the set of keys linked to the committee, and accepts a signature only when the signing key has a valid ASF UID association or follows the automated release key naming convention, containing "Automated Release Signing" or "Services RM" (ignoring case) in its primary UID with the email address private@committee.apache.org.

If a key has not been imported for the committee, or if it lacks both an ASF UID and the naming convention, signature checks will fail for artifacts signed with that key. Committee members manage these keys through the committee keys page, or through the KEYS file in SVN, depending on the committee's KEYS management mode, described in The KEYS file. See signing artifacts for background on how to create and register keys.

Podling status

If the project belongs to an incubating podling, ATR passes this to certain checks automatically. The path and naming check requires the word "incubating" in artifact filenames for podlings, and the license file check looks for a DISCLAIMER or DISCLAIMER-WIP file in the archive root. Podling status comes from the committee record and is not something that you can configure per project.