ocibuild_vcs behaviour (ocibuild v0.10.4)

View Source

Version Control System behaviour for OCI annotation support.

This module defines the behaviour for VCS adapters (Git, Mercurial, etc.) and provides detection and annotation extraction functions.

VCS adapters are used to automatically populate OCI annotations:

  • org.opencontainers.image.source - Repository URL
  • org.opencontainers.image.revision - Commit SHA/revision

Implementing an Adapter

-module(ocibuild_vcs_hg).
-behaviour(ocibuild_vcs).

-export([detect/1, get_source_url/1, get_revision/1]).

detect(Path) ->
    %% Check for .hg directory
    filelib:is_dir(filename:join(Path, ".hg")).

get_source_url(Path) ->
    %% Get default remote URL
    {ok, ~"https://example.com/repo"}.

get_revision(Path) ->
    %% Get current revision
    {ok, ~"abc123"}.

Usage

%% Detect VCS and get annotations
case ocibuild_vcs:detect("/path/to/project") of
    {ok, VcsModule} ->
        Annotations = ocibuild_vcs:get_annotations(VcsModule, "/path/to/project");
    not_found ->
        #{}
end.

Summary

Callbacks

detect(Path)

Check if this VCS manages the given path.

get_revision(Path)

Get the current revision/commit identifier.

get_source_url(Path)

Get the source repository URL.

Functions

detect(Path)

Detect which VCS manages the given path.

get_annotations(VcsModule, Path)

Get VCS annotations for the given path using the specified adapter.

Callbacks

detect(Path)

-callback detect(Path :: file:filename()) -> boolean().

Check if this VCS manages the given path.

Should check for VCS-specific markers (e.g., .git/ for Git, .hg/ for Mercurial). The implementation should walk up the directory tree to find the VCS root.

get_revision(Path)

-callback get_revision(Path :: file:filename()) -> {ok, binary()} | {error, term()}.

Get the current revision/commit identifier.

Should try CI environment variables first, then fall back to VCS commands. For Git, this is the full commit SHA. For SVN, the revision number.

get_source_url(Path)

-callback get_source_url(Path :: file:filename()) -> {ok, binary()} | {error, term()}.

Get the source repository URL.

Should try CI environment variables first for reliability, then fall back to VCS commands. The returned URL should be HTTPS for public visibility.

Functions

detect(Path)

-spec detect(file:filename()) -> {ok, module()} | not_found.

Detect which VCS manages the given path.

Walks up the directory tree checking each registered VCS adapter. Returns {ok, Module} if a VCS is found, not_found otherwise.

Example:

case ocibuild_vcs:detect("/path/to/project") of
    {ok, ocibuild_vcs_git} -> io:format("Git repository~n");
    not_found -> io:format("No VCS detected~n")
end.

get_annotations(VcsModule, Path)

-spec get_annotations(module(), file:filename()) -> #{binary() => binary()}.

Get VCS annotations for the given path using the specified adapter.

Returns a map with available annotations:

  • ~"org.opencontainers.image.source" - Repository URL (if available)
  • ~"org.opencontainers.image.revision" - Commit/revision (if available)

Missing or failed values are simply omitted from the map.

Example:

{ok, VcsModule} = ocibuild_vcs:detect(Path),
Annotations = ocibuild_vcs:get_annotations(VcsModule, Path).
%% #{~"org.opencontainers.image.source" => ~"https://github.com/org/repo",
%%   ~"org.opencontainers.image.revision" => ~"abc123..."}