Cheat sheet · Software Technology

An issue from start to merge, with commands

A cheat sheet to keep open: every step from creating an issue to cleaning up after the merge, with the git commands, how to bring develop into your branch, and fixes for the usual accidents.

6 min readIssue to branchCommit and pushMerging develop inMerge request stepsCleaning upCommon problems

One page to keep open in the first weeks: an issue from creation to merge, with the commands. ABC is your project key, origin is the GitLab repository, every command runs in the repository root. The reasons behind each rule are on the version control page; releases and hotfixes are on the final product page.

The whole path

Fig. 1 · Four columns on the board, and what you do in each. The card moves when you start and when you open the MR; the merge closes it.

0 · Once, at the start

Every member, every clone

git clone <repo-url>
cd <repo>
./setup-hooks.sh                         # cmd / PowerShell: .\setup-hooks.bat
git config user.name "Your Full Name"
git config user.email "<the e-mail address of your GitLab account>"

1 · Create the issue

Issues → New issue, template Feature or Bug.
Title in English, imperative: "Implement save/load". It becomes the branch name and the MR title.
Fill the user story and the acceptance criteria, including an error case. Set the milestone and assign yourself.
When you start: drag the card to Doing, or comment /label ~"status::doing".

2 · Start the branch

Always from an up-to-date develop

git switch develop
git pull
git switch -c feature/ABC-12-implement-save-load

# or: issue page → Create merge request → Create branch, then
git fetch && git switch feature/ABC-12-implement-save-load

3 · Work and commit

Small commits, pushed daily

git status
git add -p                               # review each change before you stage it
git commit -m "add save file validation" # the hook turns it into "ABC-12: add save file validation"
git push -u origin feature/ABC-12-implement-save-load

./gradlew spotlessApply && ./gradlew test     # or: dotnet format && dotnet test

Run the formatter and the tests before you push – don't learn from the CI that it is red. Push at least once a day, even half-finished: the branch is your backup and the team's view of your progress.

4 · Bring in develop

If teammates merged into develop while you worked, bring their changes into your branch – conflicts are then resolved by you, on your branch, before the merge (Fig. 2).

Fig. 2 · Merging develop into your branch gives it both histories. The merge request then contains only your changes, and merges without conflict.

Merge develop into your branch

git fetch origin
git merge origin/develop
# conflict: edit the files, then
git add <files> && git commit
git push

Or rebase – only before review

git fetch origin
git rebase origin/develop                # only before anyone has reviewed the branch
git push --force-with-lease              # never plain --force, never on a shared branch

5 · Open the merge request

GitLab: Merge requests → New merge request, or the link git prints after the push. Source: your branch, target: develop.
Title: the issue's title. Description: the template – what and why, how you tested it, Closes #12.
Not ready yet? Draft: in front of the title; Mark as ready when it is.
Name one teammate as reviewer and tell them on Teams. Move the card to Review.
Answer the review with new commits on the same branch, reply to every thread, then resolve it.

6 · Merge and clean up

Conditions: an approval, a green pipeline, all threads resolved, no conflict. Then the author presses Merge (merge commit, Delete source branch ticked). Closes #12 closes the issue and moves the card to Closed.

Back to develop

git switch develop
git pull
git branch -d feature/ABC-12-implement-save-load    # the remote branch was deleted by the merge

Common problems

Symptom	What to do
`remote: You are not allowed to push code to protected branches`	Good – the protection works. Create a branch and an MR.
The hook rejects the commit message	Read its output and fix the message. Not `--no-verify`. A missing key usually means you are on the wrong branch.
I committed on the wrong branch	Move the commit to a new branch, then reset the wrong one (below). Unsure? Ask before any reset --hard.
Conflict in the MR	Section 4 – the author resolves it, not the reviewer.
Red pipeline, "works for me"	Open the job log. Usually formatting, a file that isn't committed, or letter case in a file name.
A password or token got committed	Tell the team at once and replace the secret. Removing it from history is one person's job (git filter-repo); everyone re-clones afterwards.

A commit on develop that belongs on a branch

# committed on develop by mistake (not pushed yet – the server would have refused anyway)
git switch -c feature/ABC-15-pause-menu  # the new branch keeps the commit
git switch develop
git reset --hard origin/develop          # develop goes back to the server's state