CI/CD and Release

GitHub Actions workflows and the release process for Telegram Bot API Docker

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:

1. Checks out the repository code
2. Runs the shell test suite (bash tests/run.sh)
3. 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:

1. Build Docker image

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

2. Test entrypoint validation

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

3. 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:

1. Go to Actions → docker-smoke
2. Click Run workflow
3. 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:

1. Run smoke tests

   Calls the docker-smoke workflow to validate the build.

2. Set up multi-arch build environment

   • Installs QEMU for cross-platform emulation
   • Configures Docker Buildx for multi-arch builds
3. Authenticate to Docker Hub

   Logs in using repository secrets (DOCKERHUB_USERNAME and DOCKERHUB_TOKEN).

4. Extract image metadata

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

5. Build and push multi-arch image

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

6. Update Docker Hub description

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

Release Process and Versioning

To publish a new release:

1. Update version metadata

   Edit Dockerfile to update the image version label:

   LABEL org.opencontainers.image.version="9.5"
   
2. Commit changes

   git add Dockerfile
   git commit -m "chore: bump version to 9.5"
   git push origin main
   
3. Create and push version tag

   git tag v9.5
   git push origin v9.5
   
4. Monitor workflow execution

   • Go to Actions tab in GitHub
   • Watch the ci workflow run
   • Verify smoke tests pass
   • Confirm multi-arch image is published
5. 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:

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

DOCKERHUB_TOKEN

A Docker Hub access token with push permissions.

Creating a token:

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

Setting the secret:

1. Go to Settings → Secrets and variables → Actions
2. Click New repository secret
3. Name: DOCKERHUB_TOKEN
4. 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

1. QEMU emulation

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

2. Docker Buildx

   Buildx creates separate images for each platform:

   docker buildx build --platform linux/amd64,linux/arm64 ...
   
3. Manifest creation

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

4. 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

1. Go to the Actions tab in your GitHub repository
2. Select the workflow (test, docker-smoke, or ci)
3. 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