🐳 Multi-stage docker builds, publish pipelines, v2 versioning, CHANGELOG automation

.dockerignore

@@ -0,0 +1,41 @@
+# Git
+.git/
+.gitignore
+.gitmodules
+
+# CI / GitHub
+.github/
+
+# Tests and test apps
+tests/
+app_tests/
+
+# Docs and scripts (not needed in image)
+docs/
+scripts/
+
+# Markdown (keep README.md — it's copied explicitly in the Dockerfile)
+*.md
+!README.md
+
+# Python build artifacts
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Local config / secrets
+.env
+.env.*
+
+# Editor
+.vscode/
+.idea/

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## Summary
+
+<!-- What does this PR do? Why? -->
+
+## Changes
+
+<!-- Bullet points are fine. Link to relevant issues/tickets if applicable. -->
+
+## Testing
+
+<!-- How was this tested? Local smoke test, CI, manual verification, etc. -->
+
+---
+
+### Release checklist (skip for non-release PRs)
+
+<!-- Only fill this out if this PR is cutting a new release (e.g. v2.1.0). -->
+
+- [ ] `socket_basics/version.py` updated to new version
+- [ ] `pyproject.toml` `version:` field updated to match
+- [ ] `action.yml` `image:` ref updated to `docker://ghcr.io/socketdev/socket-basics:<new-version>` *(CI will fail if this doesn't match `pyproject.toml`)*
+- [ ] `CHANGELOG.md` `[Unreleased]` section reviewed *(note: this content is replaced by auto-generated release notes when the tag fires — see [docs/releasing.md](../docs/releasing.md#changelog-and-release-notes))*
+
+> ⚠️ **After merging:** run `publish-docker.yml` via `workflow_dispatch` with the new version
+> **before** creating the git tag. The image must exist in GHCR before the tag is pushed.
+> See [docs/releasing.md](../docs/releasing.md) for the full process.

.github/dependabot.yml

@@ -0,0 +1,32 @@
+version: 2
+updates:
+
+  # Main Dockerfile — tracks aquasec/trivy, trufflesecurity/trufflehog,
+  # ghcr.io/astral-sh/uv, and python base image.
+  # NOTE: OPENGREP_VERSION is not trackable via Dependabot (no Docker image);
+  #       update it manually in the Dockerfile ARG.
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "docker"
+
+  # app_tests Dockerfile — same as above, plus golang and securego/gosec.
+  - package-ecosystem: "docker"
+    directory: "/app_tests"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "docker"
+
+  # GitHub Actions — tracks all uses: ... action versions.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "github-actions"

.github/release.yml

@@ -0,0 +1,34 @@
+# Configures GitHub's auto-generated release notes categories.
+# Used by `gh release create --generate-notes` in publish-docker.yml,
+# and visible in the GitHub "Generate release notes" UI when drafting releases.
+# https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
+
+changelog:
+  categories:
+    - title: "🚀 New Features"
+      labels:
+        - enhancement
+        - feature
+    - title: "🐛 Bug Fixes"
+      labels:
+        - bug
+        - fix
+    - title: "🔒 Security"
+      labels:
+        - security
+    - title: "📦 Dependencies"
+      labels:
+        - dependencies
+        - docker
+    - title: "⚙️ CI / Build"
+      labels:
+        - ci
+        - github-actions
+        - build
+    - title: "📚 Documentation"
+      labels:
+        - documentation
+        - docs
+    - title: "🔧 Other Changes"
+      labels:
+        - "*"

.github/workflows/_docker-pipeline.yml

@@ -0,0 +1,172 @@
+name: _docker-pipeline (reusable)
+
+# Reusable workflow — the single lego brick for all Docker CI steps.
+#
+# Called by smoke-test.yml (push: false) and publish-docker.yml (push: true).
+# Step visibility is controlled by the push/tag_push inputs; the caller sets permissions.
+#
+# Two modes:
+#   push: false  →  build + smoke test + integration test (main image only)
+#   push: true   →  above + push to GHCR/Docker Hub + update floating v-tag
+#
+# Permissions required from the calling workflow:
+#   push: false  →  contents: read
+#   push: true   →  contents: write, packages: write
+
+on:
+  workflow_call:
+    inputs:
+      name:
+        description: "Image name, e.g. socket-basics"
+        type: string
+        required: true
+      dockerfile:
+        description: "Path to Dockerfile relative to repo root"
+        type: string
+        required: true
+      context:
+        description: "Docker build context"
+        type: string
+        required: false
+        default: "."
+      check_set:
+        description: "Smoke-test tool set: main or app-tests"
+        type: string
+        required: true
+      push:
+        description: "Push to GHCR and Docker Hub after testing"
+        type: boolean
+        required: false
+        default: false
+      tag_push:
+        description: >
+          True when the caller was triggered by a tag push (e.g. v2.0.0).
+          Controls the floating major-version tag update and the 'latest' Docker tag.
+          Passed explicitly rather than relying on github.ref_type inside the callee,
+          since context propagation in reusable workflows can be ambiguous.
+        type: boolean
+        required: false
+        default: false
+      version:
+        description: "Semver without v prefix (e.g. 2.0.0) — used for OCI labels and push tags"
+        type: string
+        required: false
+        default: "dev"
+    secrets:
+      DOCKERHUB_USERNAME:
+        required: false
+      DOCKERHUB_TOKEN:
+        required: false
+
+jobs:
+  pipeline:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: 🔨 Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
+
+      # Logins and metadata are only needed in push mode
+      - name: Login to GHCR
+        if: inputs.push
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ github.token }}
+
+      - name: Login to Docker Hub
+        if: inputs.push
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract image metadata
+        if: inputs.push
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        with:
+          images: |
+            ghcr.io/socketdev/${{ inputs.name }}
+            ${{ secrets.DOCKERHUB_USERNAME }}/${{ inputs.name }}
+          tags: |
+            # Tag push (v2.0.0) → Docker tags 2.0.0, 2.0, latest
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ inputs.tag_push }}
+            # workflow_dispatch re-publish → use the version input directly
+            type=raw,value=${{ inputs.version }},enable=${{ !inputs.tag_push }}
+          labels: |
+            org.opencontainers.image.title=${{ inputs.name }}
+            org.opencontainers.image.source=https://github.com/SocketDev/socket-basics
+
+      # ── Step 1: Build ──────────────────────────────────────────────────────
+      # Loads image into the local Docker daemon without pushing.
+      # Writes all layers to the GHA cache so the push step is just an upload.
+      - name: 🔨 Build (load for testing)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
+        with:
+          context: ${{ inputs.context }}
+          file: ${{ inputs.dockerfile }}
+          load: true
+          push: false
+          tags: ${{ inputs.name }}:pipeline-test
+          build-args: |
+            SOCKET_BASICS_VERSION=${{ inputs.version }}
+            VCS_REF=${{ github.sha }}
+            BUILD_DATE=${{ github.event.repository.updated_at }}
+          cache-from: type=gha,scope=${{ inputs.name }}
+          cache-to: type=gha,mode=max,scope=${{ inputs.name }}
+
+      # ── Step 2: Smoke test ─────────────────────────────────────────────────
+      - name: 🧪 Smoke test
+        run: |
+          bash ./scripts/smoke-test-docker.sh \
+            --skip-build \
+            --image-tag ${{ inputs.name }}:pipeline-test \
+            --check-set ${{ inputs.check_set }}
+
+      # ── Step 3: Integration test (main image only) ─────────────────────────
+      - name: 🔬 Integration test
+        if: inputs.name == 'socket-basics'
+        run: |
+          bash ./scripts/integration-test-docker.sh \
+            --image-tag ${{ inputs.name }}:pipeline-test
+
+      # ── Step 4: Push to registries (publish mode only) ─────────────────────
+      # All layers are in the GHA cache from step 1 — this is just an upload.
+      - name: 🚀 Push to registries
+        if: inputs.push
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
+        with:
+          context: ${{ inputs.context }}
+          file: ${{ inputs.dockerfile }}
+          load: false
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            SOCKET_BASICS_VERSION=${{ inputs.version }}
+            VCS_REF=${{ github.sha }}
+            BUILD_DATE=${{ github.event.repository.updated_at }}
+          cache-from: type=gha,scope=${{ inputs.name }}
+          provenance: true
+          sbom: true
+
+      # ── Step 5: Update floating major version tag ──────────────────────────
+      # e.g. after publishing v2.0.1, force-updates the v2 tag to point here.
+      # Only runs for the main image on tag pushes (not workflow_dispatch re-publishes).
+      - name: 🏷️ Update floating major version tag
+        if: inputs.push && inputs.tag_push && inputs.name == 'socket-basics'
+        run: |
+          MAJOR="${{ github.ref_name }}"
+          MAJOR="${MAJOR%%.*}"
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -fa "$MAJOR" -m "Update $MAJOR to ${{ github.ref_name }}"
+          git push origin "$MAJOR" --force