Inject COMMIT_SHA and BUILD_DATE at build time for /api/version

[tbrandenburg]

Background

The `/api/version` endpoint (added in #300) returns `commit_sha` and `build_date` fields, but they currently always return `"unknown"` because no build-time injection is in place:

```python
"commit_sha": os.environ.get("COMMIT_SHA", "unknown"),
"build_date": os.environ.get("BUILD_DATE", "unknown"),
```

Problem

Without CI/CD injecting these values, operators cannot use `/api/version` to verify which exact commit is running in an environment — defeating part of the feature's operational value.

Proposed Solution

Inject `COMMIT_SHA` and `BUILD_DATE` as environment variables during CI/CD pipeline execution (e.g. GitHub Actions):

```yaml
env:
COMMIT_SHA: ${{ github.sha }}
BUILD_DATE: ${{ github.event.head_commit.timestamp }}
```

For Docker deployments, pass them as build args or runtime env vars.

Acceptance Criteria

• `GET /api/version` returns the actual git SHA (not `"unknown"`) when running in CI/CD-deployed environments
• `GET /api/version` returns the actual build date when running in CI/CD-deployed environments
• Local development can still return `"unknown"` gracefully

Related

Deferred from #300 (explicitly out of scope for that PR).

[github-actions]

Hello tbrandenburg!

Thanks for your feedback!

Here are the tools I am offering:

Commands:
/ghar-commit-push
/ghar-issue-fix
/ghar-issue-investigate
/ghar-maintainability-review
/ghar-resolve-ci-errors
/ghar-review
/ghar-security-check
/ghar-stale-check

Agents:
*review

Usage:

• Use commands directly: /command-name
• Use agents with commands: *agent-name /command-name PROMPT

Example: *review /security-review Please check this code for vulnerabilities

[github-actions]

Investigation: Inject COMMIT_SHA and BUILD_DATE at build time for /api/version

Issue: #396 (#396)
Type: ENHANCEMENT
Investigated: 2026-04-28T06:15:00Z

Assessment

Metric	Value	Reasoning
Priority	MEDIUM	Issue is explicitly deferred from #300, has workaround ("unknown" fallback), and is labelled priority/medium
Complexity	LOW	Only requires adding ARG/ENV to Dockerfile and build args to 2-3 workflow files; no application code changes needed
Confidence	HIGH	The /api/version endpoint code in branch fix/issue-300-runtime-version-visibility clearly shows the expected env var names (COMMIT_SHA, BUILD_DATE), and the current Dockerfile/workflow files are straightforward to modify

---

Problem Statement

The /api/version endpoint (implemented in PR #395 on branch fix/issue-300-runtime-version-visibility) reads COMMIT_SHA and BUILD_DATE from environment variables with a fallback to "unknown". Currently, no CI/CD pipeline or Docker build process injects these values, so the endpoint always returns "unknown" in deployed environments, defeating its operational purpose.

---

Analysis

Change Rationale

Issue #300 (Critical: Add runtime version visibility) was implemented in PR #395, which added the /api/version endpoint. The implementation deliberately defers build-time injection to this issue (#396). The endpoint is designed to read from COMMIT_SHA and BUILD_DATE environment variables. To make this functional, the build system must inject these values during Docker builds in GitHub Actions.

Evidence Chain

WHY: /api/version returns "commit_sha": "unknown" and "build_date": "unknown" in deployed environments
↓ BECAUSE: No build-time injection of COMMIT_SHA and BUILD_DATE environment variables
Evidence: docker/pybackend.Dockerfile:21-23 - Only PYTHONPATH and PORT are set as ENV

↓ BECAUSE: GitHub Actions workflows don't pass build arguments during Docker builds
Evidence: .github/workflows/docker.yml:22 - Runs make docker-build without passing build args

↓ ROOT CAUSE: Dockerfile lacks ARG declarations and ENV settings for COMMIT_SHA and BUILD_DATE
Evidence: docker/pybackend.Dockerfile - No ARG or ENV for version injection

Affected Files

File	Lines	Action	Description
docker/pybackend.Dockerfile	1-26	UPDATE	Add ARG and ENV for COMMIT_SHA and BUILD_DATE
.github/workflows/docker.yml	1-68	UPDATE	Pass build args in docker-build step
.github/workflows/release.yml	1-76	UPDATE	Pass build args during release Docker builds
docker-compose.yml	1-26	UPDATE	Optionally pass env vars for local Docker development
packages/pybackend/app.py	N/A	SKIP	Endpoint already implemented in PR #395 branch

Integration Points

• /api/version endpoint (in PR feat: Add runtime version visibility via API and UI (#300) #395 branch) reads os.environ.get("COMMIT_SHA", "unknown")
• Docker builds are triggered by make docker-build → docker compose build
• GitHub Actions docker.yml runs Docker builds on push/PR to main
• GitHub Actions release.yml runs on version tags (v*)

Git History

• Introduced: 1afa304 - 2026-04-28 - "feat: Add runtime version visibility via API and UI (Critical: Add runtime version visibility (API + UI) #300)"
• Last modified: d2922b0 - 2026-04-28 - "Archive investigation for issue Critical: Add runtime version visibility (API + UI) #300"
• Implication: The endpoint is implemented but NOT yet merged to main; this issue should be implemented after PR feat: Add runtime version visibility via API and UI (#300) #395 is merged

---

Implementation Plan

Step 1: Update Dockerfile to accept build arguments

File: docker/pybackend.Dockerfile
Lines: After line 4 (after WORKDIR), before line 7 (COPY uv)
Action: UPDATE

Current code:

# syntax=docker/dockerfile:1
FROM python:3.12-slim

WORKDIR /app

# Install UV package manager
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

Required change:

# syntax=docker/dockerfile:1
FROM python:3.12-slim

ARG COMMIT_SHA=unknown
ARG BUILD_DATE=unknown

WORKDIR /app

# Install UV package manager
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

Why: Docker ARG allows passing build-time variables that can be used to set environment variables.

---

Step 2: Add ENV declarations in Dockerfile

File: docker/pybackend.Dockerfile
Lines: After line 22 (after PYTHONPATH ENV), before line 26 (CMD)
Action: UPDATE

Current code:

# Set environment variables
ENV PYTHONPATH=/app
ENV PORT=3000

# Run the application
CMD [".venv/bin/uvicorn", "app:app", "--host", "0.0.0.0", "--port", "3000"]

Required change:

# Set environment variables
ENV PYTHONPATH=/app
ENV PORT=3000
ENV COMMIT_SHA=${COMMIT_SHA}
ENV BUILD_DATE=${BUILD_DATE}

# Run the application
CMD [".venv/bin/uvicorn", "app:app", "--host", "0.0.0.0", "--port", "3000"]

Why: ENV makes the ARG values available at runtime as environment variables that the Python app can read.

---

Step 3: Update docker-compose.yml to pass build args

File: docker-compose.yml
Lines: 6-8 (build section)
Action: UPDATE

Current code:

  pybackend:
    build:
      context: .
      dockerfile: docker/pybackend.Dockerfile
    environment:
      MADE_BACKEND_PORT: 3000

Required change:

  pybackend:
    build:
      context: .
      dockerfile: docker/pybackend.Dockerfile
      args:
        - COMMIT_SHA=${COMMIT_SHA:-unknown}
        - BUILD_DATE=${BUILD_DATE:-unknown}
    environment:
      MADE_BACKEND_PORT: 3000
      COMMIT_SHA: ${COMMIT_SHA:-unknown}
      BUILD_DATE: ${BUILD_DATE:-unknown}

Why: docker-compose build args pass values to Docker ARG; environment vars ensure runtime availability. The ${VAR:-default} syntax provides defaults when the host env vars aren't set.

---

Step 4: Update GitHub Actions docker.yml workflow

File: .github/workflows/docker.yml
Lines: 21-22 (Build Docker images step)
Action: UPDATE

Current code:

      - name: Build Docker images
        run: make docker-build

Required change:

      - name: Build Docker images
        run: |
          COMMIT_SHA=${{ github.sha }} BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') make docker-build
        env:
          COMMIT_SHA: ${{ github.sha }}
          BUILD_DATE: ${{ github.event.head_commit.timestamp || github.event.repository.updated_at }}

Why: GitHub Actions provides github.sha for the commit SHA and github.event.head_commit.timestamp for the build date.

---

Step 5: Update GitHub Actions release.yml workflow

File: .github/workflows/release.yml
Lines: 43-47 (Build backend package section, add Docker build)
Action: UPDATE

Current code:

      - name: Build backend package
        run: cd packages/pybackend && uv build

Required change:

      - name: Build backend package
        run: cd packages/pybackend && uv build

      - name: Build Docker images with version info
        run: |
          COMMIT_SHA=${{ github.sha }} BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') make docker-build
        env:
          COMMIT_SHA: ${{ github.sha }}
          BUILD_DATE: ${{ github.event.head_commit.timestamp || github.event.repository.updated_at }}

Why: Release builds should also inject version info so that version-tagged releases have correct metadata.

---

Patterns to Follow

From codebase - mirror these exactly:

# SOURCE: .github/workflows/docker.yml:28-31
# Pattern for waiting for services and testing endpoints
      - name: Wait for services to be ready
        run: |
          echo "Waiting for services to start..."
          timeout 60s bash -c 'while ! curl -f http://localhost:3000/api/repositories > /dev/null 2>&1; do sleep 2; done'

# SOURCE: (from PR #395 branch) packages/pybackend/app.py
# Pattern for reading build-time environment variables with defaults
@app.get("/api/version")
def get_version():
    return {
        "version": _VERSION,
        "commit_sha": os.environ.get("COMMIT_SHA", "unknown"),
        "build_date": os.environ.get("BUILD_DATE", "unknown"),
        "environment": os.environ.get("ENVIRONMENT", "development"),
    }

---

Edge Cases & Risks

Risk/Edge Case	Mitigation
PR #395 not yet merged - /api/version endpoint doesn't exist in main	Coordinate merge order: merge PR #395 first, then implement this issue
github.event.head_commit.timestamp may be empty on PR builds	Use fallback: `github.event.head_commit.timestamp
Local development builds won't have COMMIT_SHA/BUILD_DATE	Defaults to "unknown" in both ARG and the endpoint code - graceful degradation
docker compose build without env vars will use defaults	The ${VAR:-default} syntax in docker-compose.yml handles missing vars
Windows developers using docker-compose	Use shell-compatible syntax; make docker-build abstracts OS differences

---

Validation

Automated Checks

# Verify Dockerfile syntax
docker build --build-arg COMMIT_SHA=test123 --build-arg BUILD_DATE=2026-04-28T00:00:00Z -t made-test -f docker/pybackend.Dockerfile .

# Verify the env vars are set in the container
docker run --rm made-test printenv | grep -E "COMMIT_SHA|BUILD_DATE"

# Run existing QA checks
make qa-quick

Manual Verification

1. Build Docker image with build args: COMMIT_SHA=abc123 BUILD_DATE=2026-04-28T00:00:00Z make docker-build
2. Run container: make docker-up
3. Verify endpoint: curl http://localhost:3000/api/version - should return actual values, not "unknown"
4. Verify local dev still works: unset COMMIT_SHA and BUILD_DATE, run make run, verify endpoint returns "unknown"

---

Scope Boundaries

IN SCOPE:

• Adding ARG/ENV to docker/pybackend.Dockerfile
• Updating docker-compose.yml to pass build args and environment variables
• Updating .github/workflows/docker.yml to inject values during CI builds
• Updating .github/workflows/release.yml to inject values during release builds

OUT OF SCOPE (do not touch):

• Modifying the /api/version endpoint code (already done in PR feat: Add runtime version visibility via API and UI (#300) #395)
• Adding version display to frontend UI (separate issue)
• Updating /api/health to include version (separate issue)
• Creating new workflow files or major CI/CD restructuring
• Frontend build-time injection (separate concern, different issue)

---

Metadata

• Investigated by: GHAR
• Timestamp: 2026-04-28T06:15:00Z
• Artifact: .ghar/issues/issue-396.md
• Related Issues: Critical: Add runtime version visibility (API + UI) #300 (parent), feat: Add runtime version visibility via API and UI (#300) #395 (PR implementing endpoint)
• Prerequisite: PR feat: Add runtime version visibility via API and UI (#300) #395 should be merged before implementing this change