GitHub

Version control · Project management · CI/CD

Dr. Khalil Chebil

Materials, labs and these slides:
chebil.github.io/workshops/github

Today: one project, one loop

You build calc-app, a tiny web calculator, and take it from its very first commit to a published Docker image — exactly the way software teams work.

Agenda

You watch, then you do the same in your own GitHub account. The lab pages have every step.

Before we start

✅ Post a ✅ in the chat when git --version prints a version.

Why version control?

report.docx
report_v2.docx
report_v2_final.docx
report_v2_final_FIXED.docx
report_v3_final_really_final.docx
report_v3_final_really_final (1).docx
      

Git is not GitHub

Git works without GitHub. GitHub is built on Git.

A commit is a snapshot

• A commit records the state of every file, plus author, date and a message
• It is identified by a hash: 3f9e2a1
• Each commit points to its parent: the history is a chain
• A repository is the project folder plus its whole history (.git)

Where your changes live

The staging area lets you choose what goes into the next snapshot: you can commit two files out of the three you changed.

cd ~/Downloads/calc-app          # the folder you extracted from calc-app.zip
git init                          # make it a repository
git status                        # what does Git see?
git add .                         # stage everything
git commit -m "Add the calculator app"

echo "SECRET_KEY=do-not-share" > .env
git status                        # .env is ignored, thanks to .gitignore

# on GitHub: + → New repository → calc-app, Public, no README
git remote add origin https://github.com/<you>/calc-app.git
git branch -M main
git push -u origin main
  

✅ Paste the link to your repository in the chat.

The daily loop

git status     # what changed?
git diff       # how exactly?
git add README.md
git commit -m "Add the maintainer to the README"
git push
      

Branches and the GitHub flow

• main always works. Nobody commits to it directly
• every change gets its own branch, and is merged through a pull request

Anatomy of a pull request

git switch -c add-examples              # create a branch, switch to it
# edit README.md: add an "Examples" section
git add README.md
git commit -m "Add API examples to the README"
git push -u origin add-examples         # publish the branch

# on GitHub: Compare & pull request → Create pull request
#            Files changed: comment a line → Merge → Delete branch

git switch main
git pull                                # bring the merge back
git log --oneline --graph
  

Merge conflicts

<<<<<<< HEAD
  <h1>My Calculator</h1>
=======
  <h1>Team Calculator</h1>
>>>>>>> origin/main
      

git switch -c rename-title
git commit -am "Rename the page title"
git fetch origin
git merge origin/main          # CONFLICT! Fix the file, then:
git add app/main.py
git commit -m "Merge main into rename-title"
git push -u origin rename-title  # then a pull request, and merge
  

✅ Two merged pull requests in your repository.

What you can do now

Code is only half of a project

Every team constantly asks:

Keeping the plan next to the code means it can update itself when the code changes.

Issues

Milestones and projects

Link the code to the work

In the pull request description:

Dividing by zero now returns a clear 400 error.

Closes #3
  

Merge the pull request, and GitHub does the rest:

Also works: Fixes #3, Resolves #3, in a PR or a commit message.

git switch main
git pull
git switch -c fix-divide-by-zero
# fix app/calculator.py + app/main.py
# add 2 tests
git add .
git commit -m "Return a clear error
  when dividing by zero"
git push -u origin fix-divide-by-zero
    

✅ Issue #3 closed by your PR · card in Done · milestone at 25%.

CI, CD and CD

• problems found in minutes, by a machine, not weeks later by a user
• no more "but it works on my machine"
• releasing becomes boring, and that is the goal

GitHub Actions vocabulary

Standard runners are free and unlimited for public repositories.

Anatomy of a workflow

name: CI/CD

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

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the code
        uses: actions/checkout@v6

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Install the dependencies
        run: pip install -r requirements-dev.txt

      - name: Run the tests
        run: pytest -v
  

Red, then green

Add a feature test-first: write the test, watch it fail, then make it pass.

• a failing test proves the test really tests something
• the ruleset makes CI a gate: red pull requests cannot be merged
• the log tells you why: ImportError: cannot import name 'power'

git switch main && git pull
git switch -c add-power
# tests/test_calculator.py: import power, add test_power
git commit -am "Test the power operation"
git push -u origin add-power        # PR "Closes #4" → ❌ red

# app/calculator.py: add power(), register it in OPERATIONS
git commit -am "Add the power operation"
git push                            # same PR → ✅ green → merge
  

✅ The Actions tab shows a red run and green runs · milestone at 75%.

Docker in one slide

docker build -t calc-app .
docker run -p 8000:8000 calc-app
      

Anatomy of a Dockerfile

# 1. Start from an official image that already contains Python.
FROM python:3.12-slim

# 2. Every following command runs inside /app in the container.
WORKDIR /app

# 3. Install the dependencies first. Docker caches this layer, so it is
#    only re-run when requirements.txt changes, not on every code change.
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 4. Copy the application code.
COPY app/ app/

# 5. Document the port, and say how to start the app. 0.0.0.0 makes the
#    server reachable from outside the container, not just from inside it.
EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app.main:app"]
  

git switch main && git pull
git switch -c add-docker
# create Dockerfile and .dockerignore

docker build -t calc-app .                 # build the image
docker images                              # list images
docker run --rm -p 8000:8000 calc-app      # run a container
# open http://localhost:8000 · stop with Ctrl+C
  

-p 8000:8000: port 8000 of your machine → port 8000 of the container. --rm: delete the container when it stops.
No Docker? Watch, or use a Codespace. GitHub builds the image in the next step anyway.

The full pipeline

• publish needs test: nothing broken is ever published
• pull requests are tested, never published; main and tags v* are published

The publish job

  publish:
    needs: test
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - name: Log in to the GitHub Container Registry
        uses: docker/login-action@v4
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Work out the image name and tags
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=sha

      - name: Build and push the image
        uses: docker/build-push-action@v7
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
  

# add the publish job to ci-cd.yml
# add "Run it with Docker" to README.md
git add .
git commit -m "Package the app as a
  Docker image and publish it"
git push -u origin add-docker
# PR "Closes #5" → merge → watch
#   test → publish on main

git switch main && git pull
git tag -a v1.0.0 -m "First release"
git push origin v1.0.0
    

docker run --rm -p 8000:8000 \
  ghcr.io/<you>/calc-app:1.0.0
      

✅ Green pipeline · release v1.0.0 · a public image · milestone closed.

Two hours, one complete loop

Quick quiz

1. Git or GitHub: which one works offline? Git.
2. What does git pull do? git fetch + git merge.
3. How does a pull request close issue #12? Closes #12 in its description.
4. Why does publish have needs: test? So nothing broken is ever published.
5. Image or container: which one runs? The container, an instance of an image.

More questions, with answers: page 4. Wrap-up.

Take-home challenges

Each one: issue → branch → pull request → green CI → merge. Details on the Wrap-up page.