---
checkId: check.verification.artifact.pull
plugin: stellaops.doctor.verification
severity: fail
tags: [verification, artifact, registry, supply-chain]
---
# Test Artifact Pull

## What It Checks
Requires the verification plugin to be enabled and a test artifact to be configured with either `Doctor:Plugins:Verification:TestArtifact:Reference` or `Doctor:Plugins:Verification:TestArtifact:OfflineBundlePath`.

For offline mode it checks the bundle file exists. For online mode it performs a registry `HEAD` request against the OCI manifest and optionally compares the returned digest to the expected digest.

## Why It Matters
The rest of the verification pipeline is meaningless if Doctor cannot retrieve the artifact it is supposed to validate.

## Common Causes
- No test artifact reference or offline bundle path is configured
- Registry credentials are missing or do not allow manifest access
- The artifact digest or tag points to content that no longer exists

## How to Fix

### Docker Compose
```yaml
services:
  doctor-web:
    environment:
      Doctor__Plugins__Verification__Enabled: "true"
      Doctor__Plugins__Verification__TestArtifact__Reference: ghcr.io/example/app@sha256:<digest>
```

For air-gapped mode:

```yaml
Doctor__Plugins__Verification__TestArtifact__OfflineBundlePath: /var/lib/stella/verification/offline-bundle.json
```

```bash
docker compose -f devops/compose/docker-compose.stella-ops.yml exec doctor-web crane manifest ghcr.io/example/app@sha256:<digest>
```

### Bare Metal / systemd
Use an immutable digest reference instead of a mutable tag whenever possible.

### Kubernetes / Helm
Mount registry credentials and the offline bundle path into the Doctor workload if the cluster is disconnected.

## Verification
```bash
stella doctor --check check.verification.artifact.pull
```

## Related Checks
- `check.verification.signature` - signature validation depends on the same artifact input
- `check.integration.oci.pull` - registry authorization issues often show up there too