Skip to content

README.md

Latest commit

 

History

History
118 lines (88 loc) · 3.51 KB

README.md

File metadata and controls

118 lines (88 loc) · 3.51 KB

code-provenance

Resolve Docker images in a docker-compose file to their exact source code commits on GitHub.

Installation

npm install code-provenance

Requires Node.js 20+.

CLI Usage

npx code-provenance [compose-file] [--image IMAGE] [--json] [--verbose]
  • compose-file -- path to a docker-compose file (default: docker-compose.yml)
  • --image IMAGE -- resolve a single image reference instead of a compose file
  • --json -- output results as JSON
  • --verbose, -v -- show resolution steps for each image

Examples

Resolve all images in a docker-compose file:

npx code-provenance docker-compose.yml
web: traefik:v3.6.0
  repo:       github.com/traefik/traefik
  commit:     06db5168c0d9
  status:     resolved
  confidence: exact
  url:        https://github.com/traefik/traefik/commit/06db5168c0d9...

Resolve a single image:

npx code-provenance --image ollama/ollama:0.12.3
image: ollama/ollama:0.12.3
  repo:       github.com/ollama/ollama
  commit:     b04e46da3ebc
  status:     resolved
  confidence: exact
  url:        https://github.com/ollama/ollama/commit/b04e46da3ebc...

Library Usage

import { readFileSync } from "node:fs";
import { parseCompose, parseImageRef, resolveImage } from "code-provenance";

const yaml = readFileSync("docker-compose.yml", "utf-8");
for (const [service, image] of parseCompose(yaml)) {
  const ref = parseImageRef(image);
  const result = await resolveImage(service, ref);
  console.log(`${result.service}: ${result.commit} (${result.confidence})`);
}

API Reference

Exports

  • parseCompose(yaml: string): [string, string][] -- parse a docker-compose YAML string and return [serviceName, imageString] pairs
  • parseImageRef(image: string): ImageRef -- parse a Docker image string into its components
  • resolveImage(service: string, ref: ImageRef): Promise<ImageResult> -- resolve an image reference to its source code commit
  • formatTable(results: ImageResult[]): string -- format results as a table
  • formatJson(results: ImageResult[]): string -- format results as JSON

ImageRef

Field Type Description
registry string e.g. "ghcr.io", "docker.io"
namespace string e.g. "myorg", "library"
name string e.g. "traefik", "postgres"
tag string e.g. "v3.6.0", "latest"
raw string original image string from docker-compose

ImageResult

Field Type Description
service string service name from docker-compose
image string original image string
registry string image registry
repo string | null GitHub repository URL
tag string image tag
commit string | null resolved commit SHA
commit_url string | null URL to the commit on GitHub
status string "resolved", "repo_not_found", "repo_found_tag_not_matched", or "no_tag"
resolution_method string | null how the commit was resolved (e.g. "oci_labels", "tag_match")
confidence string | null "exact" or "approximate"
steps string[] resolution steps taken (useful with --verbose)

Authentication

Set GITHUB_TOKEN for full functionality (digest resolution, :latest on GHCR, higher rate limits):

export GITHUB_TOKEN=ghp_your_token_here

Create a classic token at https://github.com/settings/tokens with read:packages scope.

License

MIT