Checkpoint Lab — Projects, Repository Settings, Visibility, Forks, Protected Resources, and Project Templates

1. Checkpoint mission and safety contract

You are onboarding a small synthetic service called catalog-api. A local Git repository already contains the authoritative first commit. Your job is to create an empty Private GitLab project, connect it without generating an unrelated server commit, prove the first push and default-branch state, inspect hosted metadata/protection, and document why this design is safer than the obvious alternatives.

• Required: Git, glab, a GitLab Free account, and a disposable personal namespace.
• No runner, pipeline minutes, cloud account, registry push, token creation, or paid feature is required.
• Do not use production source or customer data.
• Do not change project visibility to Public as part of the lab.
• Deletion is optional and not required; archive/revert/local cleanup are preferred.

2. Write predictions before creating anything

Record answers first. You will compare them with evidence later.

3. Create the authoritative local source state

Use a fresh temporary directory. The main branch and first commit exist before GitLab has any repository history.

LAB_ROOT="$(mktemp -d)"
LOCAL_DIR="$LAB_ROOT/catalog-api"
mkdir -p "$LOCAL_DIR"
cd "$LOCAL_DIR"

git init -b main
printf '# Catalog API\n\nSynthetic Chapter 03 checkpoint.\n' > README.md
printf 'node_modules/\n.env\n' > .gitignore
git add README.md .gitignore
git diff --cached --check
git commit -m "chore: initialize catalog API training project"

LOCAL_SHA_BEFORE="$(git rev-parse HEAD)"
printf 'local_head=%s\n' "$LOCAL_SHA_BEFORE"
git remote -v   # expected: no output

4. Create an empty Private project and prove the pre-push hosted state

Create the project through the REST API using a unique path. Crucially, do not set initialize_with_readme=true.

GITLAB_USER="$(glab api user --jq .username)"
LAB_NAME="catalog-api-ch03-$(date +%Y%m%d%H%M%S)"

FULL_PATH="$(glab api projects -X POST   -f "name=$LAB_NAME"   -f "path=$LAB_NAME"   -f "visibility=private"   -f "description=Disposable Chapter 03 checkpoint"   --jq .path_with_namespace)"
PROJECT_ID="$(glab repo view "$FULL_PATH" -F json --jq .id)"

glab api "projects/$PROJECT_ID"   --jq '{id,path_with_namespace,visibility,default_branch,empty_repo,archived}' 

Compare output to your prediction. On an empty project, a null/unset default branch is legitimate. Do not “fix” it by clicking Initialize README; the local repository is the declared source of truth.

5. Connect the exact GitLab project and push the first branch

Ask GitLab for the clone URL instead of typing the namespace from memory. The example uses SSH because Chapter 02 established an SSH path; if your glab configuration uses HTTPS, use the documented HTTPS URL and your credential manager.

SSH_URL="$(glab api "projects/$PROJECT_ID" --jq .ssh_url_to_repo)"
git remote add origin "$SSH_URL"

git remote -v
git status --short --branch

# First push: creates refs/heads/main on GitLab.
git push -u origin main

LOCAL_SHA="$(git rev-parse HEAD)"
REMOTE_SHA="$(git ls-remote origin refs/heads/main | awk '{print $1}')"
printf 'local=%s\nremote=%s\n' "$LOCAL_SHA" "$REMOTE_SHA"
test "$LOCAL_SHA" = "$REMOTE_SHA" && echo 'first push identity verified' 

6. Prove hosted-versus-Git state after the first push

Now inspect the GitLab project again. The branch exists and GitLab can designate a default branch. Verify, do not assume the exact protection rule inherited on your account.

glab api "projects/$PROJECT_ID"   --jq '{path_with_namespace,visibility,default_branch,empty_repo,topics,archived}'

glab api "projects/$PROJECT_ID/protected_branches"   --jq '.[] | {name,allow_force_push,push_access_levels,merge_access_levels}'

git branch -vv
git log --oneline --decorate --graph --all -n 5

Causality: the API project existed before any Git ref. The first push created refs/heads/main on the remote. The commit SHA matches because the remote received the exact local Git object graph. GitLab then exposes that ref as project/default-branch state and may apply configured protection policy around it.

7. Make one hosted-only change and prove Git is unchanged

Capture the commit SHA, update the description, and compare again.

HEAD_BEFORE_METADATA="$(git rev-parse HEAD)"

glab repo update "$FULL_PATH"   --description "Disposable Chapter 03 checkpoint — hosted metadata changed"

glab repo view "$FULL_PATH" -F json --jq '{description,visibility,default_branch}'
test "$HEAD_BEFORE_METADATA" = "$(git rev-parse HEAD)" &&   echo 'hosted metadata changed without a Git commit' 

8. Required failure drill: wrong remote, correct identity

Break only the local target. This tests whether you can distinguish authentication success from project-path authorization/targeting.

GOOD_ORIGIN="$(git remote get-url origin)"
git remote set-url origin "git@gitlab.com:synthetic-missing/ch03-checkpoint.git"

set +e
git ls-remote origin
RC=$?
set -e
printf 'broken_remote_exit=%s\n' "$RC"

# Diagnose: authentication may still be valid; target is wrong.
glab auth status
printf 'expected_project=%s\n' "$FULL_PATH"

# Least destructive repair.
git remote set-url origin "$GOOD_ORIGIN"
git ls-remote --heads origin

Do not create a broader token, request Owner, disable protection, or force-push. None of those actions correct a wrong remote URL.

9. Fork/template/blank-project decision review

10. Create a compact evidence packet

Evidence should contain identifiers and state, not credentials. Save only synthetic project metadata and Git identities.

mkdir -p "$LAB_ROOT/evidence"

glab api "projects/$PROJECT_ID"   --jq '{id,path_with_namespace,visibility,default_branch,archived,empty_repo,topics,web_url}'   > "$LAB_ROOT/evidence/project.json"

glab api "projects/$PROJECT_ID/protected_branches"   --jq '[.[] | {name,allow_force_push,push_access_levels,merge_access_levels}]'   > "$LAB_ROOT/evidence/protected-branches.json"

git rev-parse HEAD > "$LAB_ROOT/evidence/local-head.txt"
git ls-remote origin refs/heads/main > "$LAB_ROOT/evidence/remote-main.txt"
git remote -v > "$LAB_ROOT/evidence/remotes.txt"

# Inspect for accidental secrets before sharing evidence.
grep -RniE 'glpat-|PRIVATE-TOKEN|Authorization:|password=' "$LAB_ROOT/evidence" ||   echo 'no obvious credential strings found' 

11. Verification checklist

• The project path is under the intended disposable namespace.
• Visibility is Private.
• The hosted project was empty before the first push.
• Local main had one authoritative root before GitLab received a ref.
• origin points to the intended project, not merely a same-named project.
• Local HEAD equals remote refs/heads/main after the push.
• The project API reports the expected default branch after branch creation.
• Protected-ref state was inspected, not guessed.
• Description changed without changing Git HEAD.
• The intentionally broken remote was repaired without changing credentials or Git history.

12. Cleanup / rollback and project disposition

The safest course cleanup is to keep the synthetic evidence, remove the local working clone, and either leave the private disposable project for Chapter 04 or archive it after verifying the exact path. Deletion is not required.

# Verify target before any hosted cleanup.
glab repo view "$FULL_PATH" -F json   --jq '{path_with_namespace,visibility,archived,web_url}'

# Optional reversible hosted disposition after you are completely finished:
# glab repo update "$FULL_PATH" --archive=true

# Remove only the disposable local lab tree after copying evidence you want to keep.
cd /
# rm -rf -- "$LAB_ROOT"

Knowledge check

Chapter 03 summary

You can now treat GitLab project creation as architecture rather than form filling. The project is a namespace-scoped governance boundary around Git history; creation method determines initial history and upstream relationships; visibility determines exposure; paths become automation interfaces; protected refs wrap Git refs with hosted policy; archive/delete/transfer have distinct blast radii; and every mutation should be preceded and followed by evidence. This is the foundation Chapter 04 needs to reason about membership and inherited authorization.

Official references

• GitLab Docs — Create a project
• GitLab Docs — Project and group visibility
• GitLab Docs — Manage projects
• GitLab Docs — Projects API
• GitLab Docs — Forks
• GitLab Docs — Protected branches
• GitLab Docs — Protected tags
• GitLab Docs — Default branch
• GitLab Docs — Project topics
• GitLab CLI — repo commands
• GitLab CLI — repo create
• GitLab CLI — repo update
• GitLab CLI — repo fork