docker

docker

Prepare Docker build variables to match the legacy bash script.

Functions

Name	Description
base_image_name	Get base image names from a Dockerfile.
dockerfile_last_commit_iso	Get the last git commit timestamp for the Dockerfile.
dockerhub_tag_last_updated	Get Docker Hub tag `last_updated` timestamp.
evaluate_docker_build_staleness	Decide whether to build a Docker image based on Dockerfile git history and tag freshness.
evaluate_docker_build_staleness_and_set_outputs	Evaluate Docker build staleness and set step outputs.
image_tag_from_image_name	Extract the tag suffix from a Docker image name.
parse_iso_timestamp	Parse an ISO timestamp and normalize it to UTC.
prepare_docker_build_variables	Prepare Docker build variables and optionally write them to GITHUB_ENV.
tag_from_dockerfile	Extract the tag from the Dockerfile name (last extension).

base_image_name

docker.base_image_name(dockerfile)

Get base image names from a Dockerfile.

Matches the bash behavior: only lines starting with “FROM” are used and the literal “FROM” substring is removed everywhere on that line.

dockerfile_last_commit_iso

docker.dockerfile_last_commit_iso(dockerfile_path)

Get the last git commit timestamp for the Dockerfile.

Parameters

Name	Type	Description	Default
dockerfile_path	str	Path to the Dockerfile in the repository.	required

Returns

Name	Type	Description
str	str	ISO8601 timestamp from git `%cI` format, or an empty string
	str	when the file is missing, untracked, or has no git history.

dockerhub_tag_last_updated

docker.dockerhub_tag_last_updated(
    dockerhub_namespace,
    repo_name,
    image_tag,
    timeout=20,
    session=requests,
)

Get Docker Hub tag last_updated timestamp.

Parameters

Name	Type	Description	Default
dockerhub_namespace	str	Docker Hub namespace/org.	required
repo_name	str	Docker Hub repository name.	required
image_tag	str	Docker image tag.	required
timeout	int	HTTP timeout in seconds.	`20`
session		Object with a requests-compatible `get` method.	`requests`

Returns

Name	Type	Description
	Optional[str]	str or None: ISO8601 `last_updated` value, or `None` when tag is absent.

evaluate_docker_build_staleness

docker.evaluate_docker_build_staleness(
    dockerfile_path,
    image_name,
    dockerhub_namespace,
    repo_name,
)

Decide whether to build a Docker image based on Dockerfile git history and tag freshness.

Parameters

Name	Type	Description	Default
dockerfile_path	str	Path to Dockerfile in repository.	required
image_name	str	Target image name, including tag.	required
dockerhub_namespace	str	Docker Hub namespace/org.	required
repo_name	str	Docker Hub repository name.	required

Returns

Name	Type	Description
dict	Dict[str, str]	Build decision fields suitable for GitHub Action outputs.

evaluate_docker_build_staleness_and_set_outputs

docker.evaluate_docker_build_staleness_and_set_outputs(
    dockerfile_path,
    image_name,
    dockerhub_namespace,
    repo_name,
)

Evaluate Docker build staleness and set step outputs.

Parameters

Name	Type	Description	Default
dockerfile_path	str	Path to Dockerfile in repository.	required
image_name	str	Target image name, including tag.	required
dockerhub_namespace	str	Docker Hub namespace/org.	required
repo_name	str	Docker Hub repository name.	required

Returns

Name	Type	Description
dict	Dict[str, str]	Build decision fields written to GitHub Action outputs.

image_tag_from_image_name

docker.image_tag_from_image_name(image_name)

Extract the tag suffix from a Docker image name.

Parameters

Name	Type	Description	Default
image_name	str	Docker image reference, optionally including a tag.	required

Returns

Name	Type	Description
str	str	Tag string, or an empty string if no tag is present.

parse_iso_timestamp

docker.parse_iso_timestamp(raw)

Parse an ISO timestamp and normalize it to UTC.

Parameters

Name	Type	Description	Default
raw	str	ISO8601 timestamp (for example `2026-01-01T12:00:00Z`).	required

Returns

Name	Type	Description
	datetime.datetime	datetime.datetime: Timezone-aware UTC datetime.

prepare_docker_build_variables

docker.prepare_docker_build_variables(
    dockerfile,
    suffix,
    dockerhub_account,
    github_env=None,
    now=None,
)

Prepare Docker build variables and optionally write them to GITHUB_ENV.

Parameters

Name	Type	Description	Default
dockerfile	str	Path to the Dockerfile.	required
suffix	str	Suffix for the image tag (e.g., “dev”, “main”).	required
dockerhub_account	str	Docker Hub account/namespace.	required
github_env	str	Path to the GitHub Actions env file.	`None`
now	datetime	Override current time for deterministic output.	`None`

Returns

Name	Type	Description
dict	Dict[str, str]	Mapping of variable names to their values.

tag_from_dockerfile

docker.tag_from_dockerfile(dockerfile)

Extract the tag from the Dockerfile name (last extension).

Mirrors bash ${bn_dockerfile##*.} behavior.