English
Running CI
Step 1. The same checks before the push
Why. CI finds a problem a few minutes after the push, but the push is already public, and the fix needs another commit and another run. Most red runs are avoidable: if the developer runs the same checks before pushing, CI becomes a confirmation instead of a discovery. The checks must be the same, not similar — a local script that skips the audit will pass while CI fails.
That is the check command of Run.ps1, written in topic 2 and usable from now on:
powershell
'check' {
# The same steps as .github/workflows/ci.yml.
Invoke-Step dotnet 'restore', $Solution
Invoke-Step dotnet 'tool', 'restore'
Invoke-Step dotnet 'format', $Solution, '--verify-no-changes', '--no-restore'
Invoke-Step dotnet 'build', $Solution, '-c', 'Release', '--no-restore'
Invoke-Step dotnet 'ef', 'migrations', 'has-pending-model-changes', '--project', $DataProject, '--configuration', 'Release', '--no-build'
Invoke-Step dotnet 'test', '--solution', $Solution, '-c', 'Release', '--no-build'
Invoke-Step npm 'ci' -WorkingDirectory $Web
Invoke-Step npm 'audit', '--omit=dev', '--audit-level=high' -WorkingDirectory $Web
Invoke-Step npm 'run', 'format:check' -WorkingDirectory $Web
Invoke-Step npm 'run', 'lint' -WorkingDirectory $Web
Invoke-Step npm 'test', '--', '--watch=false' -WorkingDirectory $Web
Invoke-Step npm 'run', 'build' -WorkingDirectory $Web
Write-Host 'All checks passed.' -ForegroundColor Green
}Compare it with ci.yml line by line: the twelve commands are the steps of the two jobs in the same order, with the same options. Invoke-Step stops at the first failing command, as a job stops at the first failing step. Only the caches and the upload of test results have no local counterpart. When you change one file, change the other.
Do. Start Docker, then run from the repository root:
powershell
./Run.ps1 checkCheck
Every command is printed in grey before it runs (> dotnet restore Chatex.slnx, > dotnet tool restore, …). Among the output you see No changes have been made to the model since the last migration., total: 93 and failed: 0 for the backend, found 0 vulnerabilities, All matched files use Prettier code style!, All files pass linting., Tests 49 passed (49) and the table of the production build. The last line is green:
All checks passed.The first run takes a few minutes; later runs are faster because the packages and the PostgreSQL image are cached.
Docker is either not running or misconfigured
The backend tests fail with this message from Testcontainers when Docker Desktop is not started. Start it, wait until it reports that the engine is running, and run the check again.
Step 2. The dev branch and the first run
Why. The workflow runs on pushes to dev and on pull requests — not on pushes to main. This is the branch model of Chatex: everyday work goes to dev (or to short feature branches merged into dev), and main receives a finished state through a pull request. From topic 24 on, every change of main is deployed to the server, so main must only ever contain checked code.
Do. Commit the workflow on main, then create the branch dev from it and publish both branches. (If you have not created the GitHub repository yet, follow the end of Developer commands first.)
powershell
git add .powershell
git commit -m "Add the CI workflow"powershell
git pushpowershell
git switch -c devpowershell
git push -u origin devThe push of dev triggers the workflow. Open the repository on GitHub and the tab Actions: the list shows a run named after the commit message, "Add the CI workflow", with the workflow CI, the branch dev and the event push.
Check
Open the run. The graph shows two jobs, Backend and Frontend, running in parallel. Click a job to see its steps; each step expands to its log, with the same lines as in your terminal. After about five minutes both jobs have a green tick, and the commit on the Code tab of the dev branch shows a green tick too; hovering over it lists CI / Backend (push) and CI / Frontend (push).
Step 3. Reading a failed run
Why. A red run is only useful if you can find the cause quickly. Let us break a rule on purpose — on a throwaway branch, so that dev stays green — and follow the trail through a pull request.
Do. Create the branch and break the formatting of one file: open Source/Chatex.Api/Program.cs and add two spaces after var app =.
powershell
git switch -c try-redpowershell
git commit -am "Break the formatting on purpose"powershell
git push -u origin try-redOn GitHub, a banner offers Compare & pull request for the new branch. Create a pull request with base dev and compare try-red. The pull_request event starts CI for it; a push to try-red alone would not, because only dev is listed under push.
Check
The pull request shows "Some checks were not successful": Backend has a red cross, Frontend a green tick. Details next to Backend opens the job: the step Check formatting is red, the later steps are grey (skipped), and Upload test results ran because of if: failure() but found nothing to upload. The log of the red step contains
…/Source/Chatex.Api/Program.cs(14,11): error WHITESPACE: Fix whitespace formatting. Delete 2 characters. […/Source/Chatex.Api/Chatex.Api.csproj]with the file, the line and the column (the path starts with the work folder of the runner). The same error also appears as an annotation on the summary page of the run.
Close the pull request without merging, then delete the branch locally and on GitHub:
powershell
git switch devpowershell
git branch -D try-redpowershell
git push origin --delete try-redReading any red run
Start at the first red step: everything after it was skipped and says nothing. Read the end of its log first — the error is almost always in the last lines. Then reproduce it locally with the same command (./Run.ps1 check runs all of them); never "fix" CI by pushing guesses. A run that fails for a reason outside your code — a timeout while downloading packages, a GitHub outage — can be repeated with Re-run jobs on the run page.
Step 4. Protecting main
Why. Up to now CI only reports; nothing stops a red change from reaching main. GitHub rulesets turn the report into a gate: main can then change only through a pull request whose checks are green. In topic 24 this becomes vital, because every change of main is deployed.
Do. On GitHub open Settings → Rules → Rulesets → New ruleset → New branch ruleset and fill in:
- Ruleset name:
main, Enforcement status: Active; - Target branches: Add target → Include default branch (that is
main); - Branch rules: keep Restrict deletions and Block force pushes, turn on Require a pull request before merging and Require status checks to pass; under the latter, Add checks and pick Backend and Frontend.
The checks can be selected only after they have run once in the repository, which is why we ran CI first. Save the ruleset with Create.
Rulesets in private repositories
On a free personal account GitHub enforces rulesets only in public repositories. For a private repository it saves the ruleset but shows that it will not be enforced until the account is upgraded; students get GitHub Pro free of charge with the GitHub Student Developer Pack. Without enforcement, follow the rule yourself: merge into main only through a pull request with green checks.
Check
Open a pull request with base main and compare dev. It lists the checks Backend and Frontend as required, and the merge button stays disabled until both are green. Do not merge it yet: merging into main deploys from topic 24 on, and the server does not exist yet. A direct git push to main is now rejected with a message that changes must be made through a pull request (only when the ruleset is enforced).