# Setting up the team repository > A one-time checklist for the team's GitLab project: template, protected branches, merge request rules, labels, board, milestones, CI badges and a smoke test – with the GitHub equivalent of every setting. Source: https://laszlonemes.com/university/software-technology/repository-setup · Author: László Nemes Guide · Software Technology A one-time checklist for the team's GitLab project: template, protected branches, merge request rules, labels, board, milestones, CI badges and a smoke test – with the GitHub equivalent of every setting. 9 min read `Protected branches` `Merge request settings` `Labels and the issue board` `Milestones and wiki` `Smoke test` `GitLab ↔ GitHub mapping` The team's GitLab project on `szofttech.inf.elte.hu` is created for you; this guide turns it into a project that enforces the workflow: protected branches, merge request rules, labels, a board, milestones and a wiki. Do it in the first weeks – before M2 – and do it once. Everything has a GitHub equivalent, listed at the end, if your team mirrors the project there or reuses the setup later. After this session you can - set up a GitLab project so that nobody can push to main or develop - configure merge requests for merge commits, one approval and green pipelines - create the labels, board columns and milestones the workflow uses - verify the whole setup with one trial issue - map every GitLab setting to its GitHub counterpart ## The six steps Most settings need the **Maintainer** role in the project. One member does steps 1–5; the smoke test at the end involves everyone (Fig. 1). Menu paths below follow the current GitLab interface – if a name differs slightly on the server, look for the same idea nearby. > **Fig. 1** · Template, CI stack, branches, rules, planning, then one trial run that touches every piece. The setup is done when the trial run passes. > > *Diagram:* Six setup steps, done once at the start of the project: copy the template and replace KEY with the project key; pick the CI stack with one include line; push main, then create develop; protect both branches and set the merge request rules; create labels, the board, milestones and the wiki; finally take a trial issue through the whole flow. ## Copy the template Clone the team repository and copy the course's template into it (without the template's `.git` folder). It brings the contribution rules, the issue and MR templates, the git hooks, the CI pipelines per stack, `.editorconfig` and `.gitattributes`. Then replace the placeholder key with your project's 2–5 letter key: KEY → your project key ```shell # in the root of your clone, after copying the template in (without its .git folder) grep -rl "KEY-" --exclude-dir=.git . | xargs sed -i "s/KEY-/ABC-/g" # macOS: sed -i "" "s/KEY-/ABC-/g" ``` Choose your CI stack (one `include` line, see [milestone 3](https://laszlonemes.com/university/software-technology/continuous-integration)), rewrite the README for your game, and keep the line-ending rules – they save a mixed Windows/Linux team from diffs where every line looks changed: .gitattributes ```gitignore # .gitattributes – one line-ending rule for a mixed Windows / Linux / macOS team * text=auto eol=lf *.bat text eol=crlf *.sh text eol=lf *.png binary ``` ## Branches and protection The last two direct pushes ```shell git add . git commit -m "chore: add project template" git push origin main # the last direct push to main git switch -c develop git push -u origin develop # from now on, everything goes through merge requests ``` Default branch and branch names ```text Settings → Repository → Branch defaults Default branch: develop Branch name template: feature/ABC-%{id}-%{title} ``` With `develop` as the default branch, merge requests target it automatically and a fresh clone lands on it. The branch name template makes the issue page's *Create branch* button produce names like `feature/ABC-12-implement-save-load`. | Settings → Repository → Protected branches | Allowed to merge | Allowed to push and merge | Force push | | --- | --- | --- | --- | | `main` | Developers + Maintainers | No one | off | | `develop` | Developers + Maintainers | No one | off | Also protect tags matching `v*` (*Protected tags*), so a tag is only created as part of a release. The effect is simple: the only way into a protected branch is a merge request (Fig. 2). > **Fig. 2** · The rejected push is the setup working. Code reaches develop only through a merge request that passed its checks. > > *Diagram:* With protection in place, a direct push to develop is rejected by the server. The only way in is a pushed branch, a merge request into develop, and the merge checks – one approval, a green pipeline, all threads resolved – before the merge. ## Merge request rules | Settings → Merge requests | Value | Why | | --- | --- | --- | | Merge method | Merge commit | Keeps every commit and shows what belonged to one MR. | | Squash commits when merging | Do not allow | Squashing would erase the individual commits that grading reads. | | Pipelines must succeed | on | Until the pipeline exists (M3) also tick *Skipped pipelines are considered successful*, or merges are blocked. | | All threads must be resolved | on | No review comment gets lost. | | Approvals | 1 required, from the whole team | Prevent approval by the author; remove approvals when a commit is added. | | Delete source branch | on by default | With merge commits nothing is lost; the branch list stays short. | Good to know **If approval rules are not available** Approval rules depend on the server's GitLab edition. If they are missing, the rule still stands – one approval from a teammate, never your own – and the team keeps it by convention. The MR page shows whether a review happened. The MR template in `.gitlab/merge_request_templates/Default.md` is applied automatically to every new merge request; the issue templates in `.gitlab/issue_templates/` appear in the *Choose a template* list. Both are read from the default branch – another reason it must be `develop`. ## Labels, board, milestones, wiki ### Labels (Manage → Labels) | Label | Meaning | | --- | --- | | `type::feature` | New functionality – the Feature template adds it. | | `type::bug` | Something broken – the Bug template adds it. | | `type::refactor`, `type::test`, `type::docs`, `type::ci` | The other kinds of work. | | `status::todo`, `status::doing`, `status::review` | The board columns. Scoped (::) labels exclude each other. | | `priority::high` | Only when it really is. | ### Board (Plan → Issue boards) Add three lists from the `status::` labels: Todo, Doing, Review. *Open* and *Closed* stay at the edges. Dragging a card switches its label; merging an MR with `Closes #12` closes the issue and moves it to Closed. ### Milestones (Plan → Milestones) Four milestones – M1 Requirements and design, M2 Prototype I, M3 Prototype II, M4 Final product – each due on the session of week 4, 7, 10 and 13 of your semester's calendar. Every issue gets one. The milestone page shows progress; look at it before every demo. ### Wiki Make sure the wiki is enabled (*Settings → General → Visibility, project features, permissions*) and that its home page links to the design pages of [milestone 1](https://laszlonemes.com/university/software-technology/requirements-design). ## CI settings and badges - *Settings → CI/CD → Runners*: the course server has shared runners. If there is no green dot, tell your instructor. - *Settings → CI/CD → Variables*: only for secrets, such as a Unity licence. Never put secrets in the repository. - Secret push protection, if the server offers it: the server then rejects a push that contains a password or token. Two badges in the README show the state of `develop` at a glance: README badges ```md [![pipeline](https://szofttech.inf.elte.hu///badges/develop/pipeline.svg)](https://szofttech.inf.elte.hu///-/pipelines) [![coverage](https://szofttech.inf.elte.hu///badges/develop/coverage.svg)](https://szofttech.inf.elte.hu///-/pipelines) ``` ## The smoke test A setup isn't done until one issue has travelled the whole path. This also teaches every member the workflow on something harmless: The trial run ```text 1. New issue "Setup check" from the Feature template, milestone M1, assigned to you → #1 2. On the issue: Create merge request → Create branch → feature/ABC-1-setup-check 3. git fetch && git switch feature/ABC-1-setup-check, edit the README, git commit -m "verify workflow setup" → the log shows "ABC-1: verify workflow setup" 4. Push, open the MR into develop with "Closes #1", name a reviewer 5. The pipeline runs; the reviewer approves; the author merges 6. The branch is gone, issue #1 is closed, the board card moved by itself 7. git push origin main → rejected. That is the correct answer. ``` Common mistake **Still able to push to main** If step 7 succeeds, the protection is missing – and sooner or later someone will push to the wrong branch at night before a demo. Fix the protected branch settings before doing anything else. ## Every member, once On every member's machine ```shell git clone cd ./setup-hooks.sh # Windows cmd / PowerShell: .\setup-hooks.bat git config user.email # must print the address of your GitLab account ``` The hooks are what add the issue key to every commit message; without them, commits are rejected by nobody and look different from everyone else's. The e-mail check matters for grading: GitLab attributes a commit to the account whose address is in it. In your assignment **Before milestone 2** By week 7 the instructor will look at the repository itself: protected branches, the board, issues with milestones and labels, merge requests with reviews. Do the setup in the first weeks, while there is no code yet to make it painful. ## The same on GitHub The course works on GitLab, but every piece has a GitHub counterpart – useful if you mirror the project or build your next team project there. | Concept | GitLab | GitHub | | --- | --- | --- | | Asking to merge | Merge request (MR) | Pull request (PR) | | Issue templates | `.gitlab/issue_templates/*.md` | `.github/ISSUE_TEMPLATE/*.yml` | | MR / PR template | `.gitlab/merge_request_templates/Default.md` | `.github/PULL_REQUEST_TEMPLATE.md` | | Work in progress | `Draft:` in the title | Draft pull request | | Board | Issue board, columns from labels | Projects, columns from the Status field | | Scoped labels | `status::doing` | none – the Status field of Projects instead | | Branch protection | Protected branches | Rulesets | | Required approval | Approval rules | Ruleset: require a pull request, 1 approval | | CI | `.gitlab-ci.yml`, runners | `.github/workflows/*.yml`, Actions | | Security scanning | SAST and Secret Detection templates | CodeQL and secret scanning | | Merge only an up-to-date branch | Merged results pipelines | Require branches to be up to date | | Dependency updates | Renovate (optional) | Dependabot | | Closing an issue | `Closes #12` in the MR | `Closes #12` in the PR | On GitHub, turn off squash and rebase merging, enable *Automatically delete head branches*, and in the ruleset require one approval, conversation resolution and the CI checks. Branch protection on a private repository needs a paid plan or the student pack.