CI/CD and Release

This page documents the continuous integration and deployment workflows that automate testing, building, and publishing the Docker images.

GitHub Actions Workflows Overview

The project uses three GitHub Actions workflows:

Workflow	Trigger	Purpose
`test`	Push/PR to `main`	Runs entrypoint tests
`docker-smoke`	Manual or reusable	Validates Docker build and runtime
`docker-release`	Version tags (`v.`)	Builds and publishes multi-arch images

Test Workflow

File: .github/workflows/test.yml Trigger: Runs on every push or pull request targeting the main branch.

name: test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  shell-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Run entrypoint.sh tests
        run: bash tests/run.sh

What it does:

Checks out the repository code
Runs the shell test suite (bash tests/run.sh)
Fails the build if any test fails

Local equivalent:

bash tests/run.sh

This workflow does NOT build the Docker image. It only validates the entrypoint script logic using mock binaries.

Docker Smoke Workflow

File: .github/workflows/docker-smoke.yml Trigger:

Manual dispatch (workflow_dispatch)
Called by other workflows (workflow_call)

name: docker-smoke

on:
  workflow_dispatch:
  workflow_call:

jobs:
  build-and-smoke:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build Docker image (native arch)
        uses: docker/build-push-action@v6
        with:
          context: .
          file: ./Dockerfile
          load: true
          tags: tbapi:test
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: EntryPoint env validation should fail without env
        run: |
          set +e
          out=$(docker run --rm tbapi:test 2>&1)
          status=$?
          echo "$out"
          set -e
          if [ "$status" -eq 0 ]; then
            echo "Expected non-zero exit when env vars are missing" >&2
            exit 1
          fi
          echo "$out" | grep -q "Error: TELEGRAM_API_ID is not set"

      - name: Binary exists and prints version
        run: |
          docker run --rm --entrypoint ./telegram-bot-api tbapi:test --version 2>&1 | tee version.txt
          grep -Eiq "bot api" version.txt

What it does:

Build Docker image

Builds the image for the runner’s native architecture (AMD64).

Test entrypoint validation

Verifies that the container exits with an error when required environment variables are missing.

Verify binary

Confirms that the telegram-bot-api binary exists and responds to --version.

Running manually: You can trigger this workflow from the GitHub Actions tab:

Go to Actions → docker-smoke
Click Run workflow
Select the branch and click Run workflow

Docker Release Workflow

File: .github/workflows/docker-release.yml Trigger: Pushing a version tag matching v*.* (e.g., v9.5, v9.5.0)

name: ci

on:
  push:
    tags: "v*.*"

env:
  IMAGE_NAME: ${{ github.repository }}

jobs:
  smoke-test:
    uses: ./.github/workflows/docker-smoke.yml

  publish:
    runs-on: ubuntu-latest
    needs: smoke-test
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Set up QEMU (for multi-arch)
        uses: docker/setup-qemu-action@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Docker Hub
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Extract metadata
        id: metadata
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.IMAGE_NAME }}

      - name: Build and push (multi-arch)
        uses: docker/build-push-action@v6
        with:
          context: .
          file: ./Dockerfile
          push: ${{ github.event_name != 'pull_request' }}
          platforms: linux/amd64,linux/arm64
          tags: ${{ steps.metadata.outputs.tags }}
          labels: ${{ steps.metadata.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Docker Hub Description
        uses: peter-evans/dockerhub-description@v5
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
          repository: ${{ env.IMAGE_NAME }}

What it does:

Run smoke tests

Calls the docker-smoke workflow to validate the build.

Set up multi-arch build environment

Installs QEMU for cross-platform emulation
Configures Docker Buildx for multi-arch builds

Authenticate to Docker Hub

Logs in using repository secrets (DOCKERHUB_USERNAME and DOCKERHUB_TOKEN).

Extract image metadata

Generates tags and labels from the Git tag (e.g., v9.5 → ragnarok22/telegram-bot-api-docker:9.5).

Build and push multi-arch image

Builds for both linux/amd64 and linux/arm64, then pushes to Docker Hub.

Update Docker Hub description

Syncs the repository’s README to the Docker Hub page.

Release Process and Versioning

To publish a new release:

Update version metadata

Edit Dockerfile to update the image version label:

LABEL org.opencontainers.image.version="9.5"

Commit changes

git add Dockerfile
git commit -m "chore: bump version to 9.5"
git push origin main

Create and push version tag

git tag v9.5
git push origin v9.5

Monitor workflow execution

Go to Actions tab in GitHub
Watch the ci workflow run
Verify smoke tests pass
Confirm multi-arch image is published

Verify Docker Hub

Check that the new tag appears on Docker Hub:

docker pull ragnarok22/telegram-bot-api-docker:9.5
docker run --rm ragnarok22/telegram-bot-api-docker:9.5 ./telegram-bot-api --version

Version Tag Formats

The workflow triggers on tags matching v*.*: Valid tags:

v9.5 → Published as 9.5 and latest
v9.5.0 → Published as 9.5.0 and latest
v10.0 → Published as 10.0 and latest

Invalid tags (will NOT trigger):

9.5 (missing v prefix)
release-9.5 (doesn’t match pattern)
v9 (requires at least two version components)

Always use the v prefix and at least two version components (e.g., v9.5) to trigger the release workflow.

Required Secrets

The release workflow requires two GitHub repository secrets:

`DOCKERHUB_USERNAME`

Your Docker Hub username. Setting the secret:

Go to Settings → Secrets and variables → Actions
Click New repository secret
Name: DOCKERHUB_USERNAME
Value: Your Docker Hub username (e.g., ragnarok22)

`DOCKERHUB_TOKEN`

A Docker Hub access token with push permissions. Creating a token:

Log in to Docker Hub
Go to Account Settings → Security → Access Tokens
Click New Access Token
Name: github-actions-telegram-bot-api
Permissions: Read, Write, Delete
Copy the token (you won’t see it again)

Setting the secret:

Go to Settings → Secrets and variables → Actions
Click New repository secret
Name: DOCKERHUB_TOKEN
Value: Paste the access token

Never commit secrets to the repository or expose them in workflow logs. GitHub automatically masks secret values in logs.

Multi-Arch Image Publishing

The release workflow builds for two architectures:

Platform	Architecture	Use Case
`linux/amd64`	x86_64	Most cloud servers, Intel/AMD desktops
`linux/arm64`	ARM 64-bit	Apple Silicon, ARM servers, Raspberry Pi 4+

How Multi-Arch Works

QEMU emulation

The docker/setup-qemu-action installs QEMU, allowing the AMD64 runner to build ARM64 images.

Docker Buildx

Buildx creates separate images for each platform:

docker buildx build --platform linux/amd64,linux/arm64 ...

Manifest creation

Docker creates a manifest list that references both architecture-specific images.

Automatic selection

When users run docker pull ragnarok22/telegram-bot-api-docker:9.5, Docker automatically selects the correct image for their platform.

Build Cache

The workflow uses GitHub Actions cache to speed up builds:

cache-from: type=gha
cache-to: type=gha,mode=max

Benefits:

Subsequent builds reuse unchanged layers
Multi-arch builds share cache between platforms
Reduces build time from ~15 minutes to ~3 minutes

Monitoring CI/CD

Viewing Workflow Runs

Go to the Actions tab in your GitHub repository
Select the workflow (test, docker-smoke, or ci)
Click a specific run to view logs

Build Status Badges

Add status badges to your README:

[![test](https://github.com/ragnarok22/telegram-bot-api-docker/actions/workflows/test.yml/badge.svg)](https://github.com/ragnarok22/telegram-bot-api-docker/actions/workflows/test.yml)
[![docker-release](https://github.com/ragnarok22/telegram-bot-api-docker/actions/workflows/docker-release.yml/badge.svg)](https://github.com/ragnarok22/telegram-bot-api-docker/actions/workflows/docker-release.yml)

Common Build Failures

Error	Cause	Solution
`DOCKERHUB_USERNAME not found`	Missing secret	Add repository secret
`authentication failed`	Invalid token	Regenerate Docker Hub token
`platform not supported`	QEMU not set up	Ensure `setup-qemu-action` runs
`test failed`	Entrypoint bug	Fix code and re-run tests
`tag already exists`	Duplicate version	Use a new version tag

Local Multi-Arch Build

You can replicate the release build locally:

# Create and use a Buildx builder
docker buildx create --name multi-arch-builder --use

# Build for multiple platforms (without pushing)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t telegram-bot-api:local-multi \
  .

# Build and load for local testing (single platform)
docker buildx build \
  --platform linux/amd64 \
  -t telegram-bot-api:local-amd64 \
  --load \
  .

The --load flag only works with a single platform. For multi-arch images, you must push to a registry or use docker buildx build --output type=oci,dest=image.tar.

Best Practices

Test before tagging

Always run bash tests/run.sh locally before creating a release tag.

Semantic versioning

Follow upstream Telegram Bot API version numbers (e.g., v9.5).

Update labels

Keep org.opencontainers.image.version in sync with Git tags.

Monitor workflows

Watch the Actions tab during releases to catch issues early.

Troubleshooting

Workflow doesn’t trigger on tag push

Check:

Tag matches v*.* pattern (e.g., v9.5, not 9.5)
Tag was pushed to the repository: git push origin v9.5
Workflow file exists in the tagged commit

Multi-arch build is slow

Causes:

Cross-compilation uses QEMU emulation (ARM64 builds on AMD64 runners)
No cache from previous runs

Solutions:

First build will always be slow (~15 minutes)
Subsequent builds reuse cache (~3 minutes)
Use native runners for each architecture (requires GitHub Enterprise)

Docker Hub description not updated

Check:

DOCKERHUB_TOKEN has read/write permissions
Repository name matches github.repository (org/repo format)
README.md exists in the repository root

Build succeeds but image doesn’t work

Debug:

# Pull the published image
docker pull ragnarok22/telegram-bot-api-docker:9.5

# Test entrypoint validation
docker run --rm ragnarok22/telegram-bot-api-docker:9.5 2>&1 | grep "Error: TELEGRAM_API_ID"

# Test binary
docker run --rm --entrypoint ./telegram-bot-api ragnarok22/telegram-bot-api-docker:9.5 --version

# Run with shell access
docker run --rm -it --entrypoint sh ragnarok22/telegram-bot-api-docker:9.5

Overview

Setup & Deployment

Configuration

Operations

Migration

Development

Reference

GitHub Actions Workflows Overview

Test Workflow

Docker Smoke Workflow

Docker Release Workflow

Release Process and Versioning

Version Tag Formats

Required Secrets

`DOCKERHUB_USERNAME`

`DOCKERHUB_TOKEN`

Multi-Arch Image Publishing

How Multi-Arch Works

Build Cache

Monitoring CI/CD

Viewing Workflow Runs

Build Status Badges

Common Build Failures

Local Multi-Arch Build

Best Practices

Test before tagging

Semantic versioning

Update labels

Monitor workflows

Troubleshooting

Workflow doesn’t trigger on tag push

Multi-arch build is slow

Docker Hub description not updated

Build succeeds but image doesn’t work

Build docs developers (and LLMs) love

Overview

Setup & Deployment

Configuration

Operations

Migration

Development

Reference

Documentation Index

​GitHub Actions Workflows Overview

​Test Workflow

​Docker Smoke Workflow

​Docker Release Workflow

​Release Process and Versioning

​Version Tag Formats

​Required Secrets

​DOCKERHUB_USERNAME

​DOCKERHUB_TOKEN

​Multi-Arch Image Publishing

​How Multi-Arch Works

​Build Cache

​Monitoring CI/CD

​Viewing Workflow Runs

​Build Status Badges

​Common Build Failures

​Local Multi-Arch Build

​Best Practices

Test before tagging

Semantic versioning

Update labels

Monitor workflows

​Troubleshooting

​Workflow doesn’t trigger on tag push

​Multi-arch build is slow

​Docker Hub description not updated

​Build succeeds but image doesn’t work

Build docs developers (and LLMs) love

GitHub Actions Workflows Overview

Test Workflow

Docker Smoke Workflow

Docker Release Workflow

Release Process and Versioning

Version Tag Formats

Required Secrets

`DOCKERHUB_USERNAME`

`DOCKERHUB_TOKEN`

Multi-Arch Image Publishing

How Multi-Arch Works

Build Cache

Monitoring CI/CD

Viewing Workflow Runs

Build Status Badges

Common Build Failures

Local Multi-Arch Build

Best Practices

Troubleshooting

Workflow doesn’t trigger on tag push

Multi-arch build is slow

Docker Hub description not updated

Build succeeds but image doesn’t work