I did not add CI to Knot Forget before the Django project existed. There would not have been much point: nothing meaningful to install, lint, or test.

I added it at the first moment where it could prove something useful. The project could boot, dependencies were managed, settings loaded, Ruff had rules to enforce, and pytest could run a smoke test against a minimal home view. There was still no domain logic, no models, no real API, and no feature work worth protecting by hand.

That timing is the part I care about.

Add CI after the project has a real baseline, but before the codebase feels important enough for exceptions.

The first pipeline should be boring

The first CI pipeline does not need to predict the future. Mine has two jobs: lint and test.

The lint job installs the project dependencies, runs Ruff checks, and verifies formatting. The test job installs the same dependencies and runs pytest. There is no deployment step, no Docker image publishing, no coverage threshold, and no database service yet. Those can come later, when the project actually needs them.

At this stage, CI has a narrower job: make every pull request prove that the project still has a working baseline.

name: CI

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

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v6
        with:
          enable-cache: true
      - run: uv sync --frozen
      - run: uv run ruff check .
      - run: uv run ruff format --check .

  test:
    runs-on: ubuntu-latest
    env:
      DJANGO_SECRET_KEY: ci-dummy-secret-key-not-used-in-production
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v6
        with:
          enable-cache: true
      - run: uv sync --frozen
      - run: uv run pytest

The stack is specific to this project: GitHub Actions, uv, Ruff, pytest, Django. The shape is not. Install the project reproducibly, check the code, run the tests, and keep the first version small enough that a failure means something.

A complicated first pipeline is easy to explain away. A boring one is harder to argue with.

A check that is not required is only a suggestion

Adding a workflow file is not the whole job. If CI runs but failed checks do not block merging, the pipeline is mostly informational: useful, but not structural. It tells you something went wrong, then leaves the decision to whoever is tired enough to merge anyway.

The important step is making the checks required on main.

For Knot Forget, the branch ruleset requires both lint and test before a pull request can merge. Once that is true, CI becomes part of the repository contract. Nobody has to remember to ask whether the checks passed, and nobody has to decide whether this lint failure is acceptable because the change is small.

The repository answers before the merge button does.

That matters even on a solo project. Especially on a solo project. The person most likely to bypass a weak process is usually the same person who created it, late in the evening, convinced the patch is harmless.

Required checks remove that negotiation.

CI caught the first missing piece immediately

The first version of the workflow did not include an env block in the test job.

Locally, tests passed. That made sense: my machine already had the project environment in place. The .env file existed, the settings could read what they needed, and Django could start.

Then CI ran for the first time, on a clean GitHub runner, with only the repository and the workflow instructions available. The test job failed before it reached any meaningful application behavior. Django tried to load settings, settings required DJANGO_SECRET_KEY, and the runner did not have one.

That was not a problem with CI. That was CI doing exactly what I added it to do.

The first useful thing CI did was disagree with my machine.

The pipeline had found a real assumption: the project needed an environment variable to boot, and the workflow had not declared it. Without CI, I could have kept running tests locally and missed that detail for longer, because the code looked healthy on the one machine that already had the missing piece.

The fix was small:

test:
  runs-on: ubuntu-latest
  env:
    DJANGO_SECRET_KEY: ci-dummy-secret-key-not-used-in-production
  steps:
    - uses: actions/checkout@v4
    - uses: astral-sh/setup-uv@v6
      with:
        enable-cache: true
    - run: uv sync --frozen
    - run: uv run pytest

The important part is not that the value is fake. Of course a test job should not use a production secret. The important part is that the test job now declares what the project needs in order to start.

That is what even a basic CI pipeline gives you. With only lint and test, the repository has to prove that a fresh runner can install the project, check the code, and run the test suite. That is a stronger statement than "it works on my laptop". It means the code works from the instructions committed to the repo.

The smoke test is the first contract

At this point in the project, there was not much behavior to test. That was fine. The smoke test only needed to prove that Django could start and serve the minimal home view; it was not pretending to validate domain behavior that did not exist yet.

That small test still carried weight. It forced the settings module to load, forced required environment to be present, and made CI exercise the same bootstrap path future tests will build on.

A first smoke test is not about coverage. It is about proving the project can stand up in a clean environment.

That phrase matters. Local tests are necessary, but they are not enough to prove bootstrap. Your machine accumulates state: a .env file exists because you created it earlier, a dependency may already be installed, a shell variable may still be set. A command can pass locally for reasons that are not visible in the repository.

CI removes most of that accidental help. For a new project, one smoke test on a clean runner can reveal missing setup assumptions before they harden into undocumented project knowledge.

CI has to run once before GitHub can require it

There is one awkward detail in GitHub branch protection: a status check has to exist before it can be selected as required.

So the sequence is not quite "decide the check names, require them, then add CI". In practice, it is closer to this: add the workflow, open a pull request, let the jobs run once, fix whatever the clean runner exposes, then add the resulting lint and test checks to the branch ruleset.

That first run is not just ceremony to make GitHub display the check names. It is the first clean-room execution of the project. It is where missing environment, incomplete setup instructions, and false local assumptions show up.

Once that run is green, requiring the checks means something. You are not requiring an imagined pipeline. You are requiring a command path that has already survived outside your machine.

The timing is the decision

"Set up CI from day one" is close, but not quite the rule I would use.

Day one might be too early. Before the project can boot, CI is mostly ceremony: you can add an empty workflow, but it does not protect much. "Set up CI later" is worse, because later usually means after feature work begins, after conventions have started drifting, and after local assumptions have become invisible.

The useful moment is in between.

Add CI when the project can boot: when there is one real command to lint, one real command to test, and one minimal path through application startup. Then run those commands somewhere clean enough to disagree with your machine.

That disagreement is the point.

In my case, the first CI run immediately caught that the test job was missing DJANGO_SECRET_KEY. The fix was one line, but the signal was larger: the project was not fully reproducible from the repository yet.

That is why I want CI as soon as the project can meaningfully pass through it. Not because the pipeline is mature, and not because there is much behavior to test yet, but because even a small lint + test pipeline forces the code to prove it works somewhere clean.

Building Knot Forget in public · Threads