Create the project

Goal: a project folder with the app, tests, requirements, and an empty workflow folder.

1. Create the folder structure:

   mkdir py-hello && cd py-hello
   mkdir -p .github/workflows
   touch app.py test_app.py requirements.txt .github/workflows/ci.yml

2. Open app.py and type the code below yourself. The point is to read each line.

   from http.server import BaseHTTPRequestHandler, HTTPServer
   import json
   import os
   
   
   def greet(name: str = "world") -> str:
       return f"Hello, {name}!"
   
   
   class Handler(BaseHTTPRequestHandler):
       def do_GET(self):
           if self.path == "/health":
               body = {"status": "ok"}
           else:
               body = {"message": greet()}
           payload = json.dumps(body).encode()
           self.send_response(200)
           self.send_header("Content-Type", "application/json")
           self.send_header("Content-Length", str(len(payload)))
           self.end_headers()
           self.wfile.write(payload)
   
   
   if __name__ == "__main__":
       port = int(os.environ.get("PORT", "8000"))
       print(f"Listening on port {port}")
       HTTPServer(("0.0.0.0", port), Handler).serve_forever()

3. Put one line in requirements.txt: pytest
4. Check that the server starts, then stop it with Ctrl+C:

   python app.py
   # Expected: Listening on port 8000

If python is not found: try python3, or check the install with python --version.

Test and run locally

Goal: tests pass and the server responds before anything goes to GitHub.

1. Write test_app.py:

   from app import greet
   
   
   def test_greet_default():
       assert greet() == "Hello, world!"
   
   
   def test_greet_with_name():
       assert greet("Bastian") == "Hello, Bastian!"

2. Create a virtual environment, activate it, and install dependencies:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

   Windows PowerShell: .venv\Scripts\Activate.ps1

3. Run the tests. Expect 2 passed:

   pytest -v

4. Start the server in the background and query it:

   python app.py &
   curl localhost:8000
   curl localhost:8000/health
   # {"message": "Hello, world!"}
   # {"status": "ok"}

5. Stop the background server, then ignore generated files:

   kill %1
   printf ".venv/\n__pycache__/\n.pytest_cache/\n" > .gitignore

ModuleNotFoundError: app means pytest ran from a subfolder. Run it from the project root.

Address already in use means port 8000 is taken. Stop the other process, or run PORT=8001 python app.py and curl port 8001.

Add the pipeline and push

Goal: the code is in a private GitHub repository and the first pipeline run has started.

1. Write .github/workflows/ci.yml:

   name: CI
   
   on:
     push:
       branches: [main]
     pull_request:
     workflow_dispatch:
   
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
   
         - uses: actions/setup-python@v5
           with:
             python-version: "3.12"
   
         - name: Install dependencies
           run: pip install -r requirements.txt
   
         - name: Run tests
           run: pytest -v
   
         - name: Smoke test the server
           run: |
             python app.py &
             sleep 2
             curl -f http://localhost:8000/health

   on sets when the workflow runs. Each item under steps runs in order on a fresh Ubuntu machine. The smoke test starts the app and checks that /health responds.

2. Make the first commit:

   git init -b main
   git add .
   git commit -m "Add app, tests, and CI"

3. Create the repository and push. Choose one option.

   # Option A: GitHub CLI
   gh auth login
   gh repo create py-hello --private --source=. --push
   
   # Option B: web UI
   # Create an empty private repo named py-hello on github.com, then:
   git remote add origin https://github.com/<your-user>/py-hello.git
   git push -u origin main

4. Open the Actions tab in the repository and open the run for your commit.

Workflow does not appear: confirm the file is at .github/workflows/ci.yml, the YAML indentation is correct, and you pushed to main.

Watch a build, then break it

Fix, re-trigger, and verify

gh workflow run says the workflow was not found: the file must exist on the default branch. Confirm that main contains ci.yml.