ci(docker): implement Docker Hub publishing workflow

.github/workflows/docker-publish.yml

@@ -0,0 +1,43 @@
+name: Publish Docker Image
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+env:
+  IMAGE_NAME: ${{ vars.DOCKERHUB_IMAGE || format('{0}/song-vault', secrets.DOCKERHUB_USERNAME) }}
+
+jobs:
+  dockerhub:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=tag
+
+      - name: Build and push image
+        uses: docker/build-push-action@ee4ca427a2f43b6a16632044ca514c076267da23 # v6.19.0
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

README.md

@@ -77,6 +77,23 @@ TEST_DATABASE_URL=postgresql+asyncpg://song_vault:song_vault@localhost:5432/song
 uv run pre-commit run --all-files
 ```
 
+## Docker Hub publish pipeline
+
+The repository includes a GitHub Actions workflow at `.github/workflows/docker-publish.yml` that builds and pushes the app image to Docker Hub on:
+
+- pushes of Git tags matching `v*`
+
+The published Docker tag is the same as the Git tag that triggered the workflow (for example, pushing `v1.2.3` publishes the Docker tag `v1.2.3`).
+
+Set these GitHub Actions secrets:
+
+- `DOCKERHUB_USERNAME`
+- `DOCKERHUB_TOKEN` (Docker Hub access token)
+
+Optional repository variable:
+
+- `DOCKERHUB_IMAGE` (defaults to `<DOCKERHUB_USERNAME>/song-vault`)
+
 ## Environment variables
 
 - `TELEGRAM_BOT_TOKEN`: bot token from BotFather

docs/features/README.md

@@ -11,5 +11,6 @@ This directory holds implementation notes for shipped features and feature fixes
 ## Current status
 
 - [Button navigation cleanup](button-navigation-cleanup.md)
+- [Docker Hub publish pipeline](dockerhub-publish-pipeline.md)
 - [Song artist and source URL split](song-artist-source-url-split.md)
 - [Ukrainian-only bot localization](ukrainian-localization.md)

docs/features/dockerhub-publish-pipeline.md

@@ -0,0 +1,29 @@
+# Docker Hub Publish Pipeline
+
+## Summary
+
+Adds a deployment pipeline that builds and publishes the bot Docker image to Docker Hub.
+
+## What changed
+
+- Added `.github/workflows/docker-publish.yml`.
+- Triggers:
+  - push of Git version tags matching `v*`
+- Added Docker Hub login and image publish steps only (no runtime deploy target yet).
+- Added Docker metadata tagging for git tags only.
+- Enforced Docker image tag parity with the pushed Git tag (for example, `v1.2.3` -> `v1.2.3`).
+- Configured GitHub Actions cache for Docker Buildx layers.
+
+## Security and reproducibility
+
+- Action references are pinned to immutable commit SHAs while still tracking the latest major release tags at implementation time:
+  - `actions/checkout@v6.0.1`
+  - `docker/login-action@v3.7.0`
+  - `docker/metadata-action@v5.10.0`
+  - `docker/build-push-action@v6.19.0`
+
+## Required GitHub configuration
+
+- `DOCKERHUB_USERNAME` (secret)
+- `DOCKERHUB_TOKEN` (secret, Docker Hub access token)
+- Optional `DOCKERHUB_IMAGE` (repository variable). If unset, defaults to `<DOCKERHUB_USERNAME>/song-vault`.