build: add version tagging and labeling to Docker images and workflow

- Pass VERSION as a build argument in Docker workflow jobs
- Update README with instructions for building Docker images with version tags and verifying image version labels
- Add VERSION build argument to Dockerfile and set version labels for both OCI and Label Schema standards

Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>

Author: appleboy

.github/workflows/docker.yml

@@ -71,6 +71,8 @@ jobs:
           push: false
           load: true
           tags: ${{ env.REPO }}:scan
+          build-args: |
+            VERSION=${{ steps.docker-meta.outputs.version }}
 
       - name: Run Trivy vulnerability scanner on Docker image
         uses: aquasecurity/trivy-action@0.33.1
@@ -95,5 +97,7 @@ jobs:
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.docker-meta.outputs.tags }}
           labels: ${{ steps.docker-meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ steps.docker-meta.outputs.version }}
           cache-from: type=registry,ref=ghcr.io/${{ env.REPO }}:buildcache
           cache-to: type=registry,ref=ghcr.io/${{ env.REPO }}:buildcache,mode=max

README.md

@@ -211,7 +211,14 @@ AuthGate provides multi-architecture Docker images for easy deployment:
 make build_linux_amd64  # For Linux x86_64
 make build_linux_arm64  # For Linux ARM64
 
-# Build Docker image
+# Build Docker image (with version tag)
+docker build -f docker/Dockerfile \
+  --build-arg VERSION=v1.0.0 \
+  -t authgate:v1.0.0 \
+  -t authgate:latest \
+  .
+
+# Or build without version (defaults to "dev")
 docker build -f docker/Dockerfile -t authgate .
 
 # Run with Docker
@@ -226,6 +233,9 @@ docker run -d \
 
 # Check health
 curl http://localhost:8080/health
+
+# Inspect image labels to verify version
+docker inspect authgate:v1.0.0 | grep -A 5 Labels
 ```
 
 #### Docker Features
@@ -236,6 +246,7 @@ curl http://localhost:8080/health
 - Built-in health check endpoint
 - Persistent volume for SQLite database
 - Embedded templates and static files (single binary)
+- Version labels via `--build-arg VERSION=<version>` (supports both OCI and Label Schema standards)
 
 #### Docker Compose Example
 
@@ -702,6 +713,14 @@ systemctl start authgate
 #### 2. Docker Deployment
 
 ```bash
+# Build with version information
+VERSION=$(git describe --tags --always --dirty)
+docker build -f docker/Dockerfile \
+  --build-arg VERSION=${VERSION} \
+  -t authgate:${VERSION} \
+  -t authgate:latest \
+  .
+
 # Using Docker Compose (recommended)
 docker-compose up -d
 
@@ -715,6 +734,9 @@ docker run -d \
   -e SESSION_SECRET=$(openssl rand -hex 32) \
   -e BASE_URL=https://auth.yourdomain.com \
   authgate:latest
+
+# Verify deployed version
+docker inspect authgate:latest --format '{{index .Config.Labels "org.opencontainers.image.version"}}'
 ```
 
 #### 3. Reverse Proxy Setup (Nginx)

docker/Dockerfile

@@ -2,15 +2,18 @@ FROM alpine:3.21
 
 ARG TARGETOS
 ARG TARGETARCH
+ARG VERSION=dev
 
 LABEL maintainer="AuthGate Team" \
   org.label-schema.name="AuthGate" \
   org.label-schema.vendor="AuthGate" \
-  org.label-schema.schema-version="1.0"
+  org.label-schema.schema-version="1.0" \
+  org.label-schema.version="${VERSION}"
 
 LABEL org.opencontainers.image.source=https://github.com/your-org/authgate
 LABEL org.opencontainers.image.description="OAuth 2.0 Device Authorization Grant server for CLI tools and browserless devices"
 LABEL org.opencontainers.image.licenses=MIT
+LABEL org.opencontainers.image.version="${VERSION}"
 
 RUN apk add --no-cache ca-certificates wget && \
   rm -rf /var/cache/apk/* && \