070-gitlab-ops

VCS Operations Reference (GitLab & GitHub)

Single source of truth for all VCS CLI commands, label taxonomy, issue templates, and project resolution.

VCS Auto-Detection

Detect which platform the current repo uses:

REMOTE_URL=$(git remote get-url origin 2>/dev/null)
if echo "$REMOTE_URL" | grep -q "github.com"; then
  VCS=github    # use `gh`
else
  VCS=gitlab    # use `glab`
fi

Session Config overrides:

• vcs: github|gitlab -- force a specific platform
• gitlab-host: <host> -- override auto-detected GitLab host

Canonical Project Identity

GitLab REST endpoints accept a URL-encoded namespace/project path. Select the GitLab host and project path explicitly; never derive a numeric project ID from glab repo view, a search query, or :id placeholders. Those forms can resolve through the ambient working directory or a stale search result and target another project after a rename, fork, or scaffold.

Set the identity once per operation sequence and reuse the encoded identifier without encoding it again:

GITLAB_HOST="<selected GitLab hostname>"
GROUP_PATH="<selected group path>"
PROJECT_NAME="<selected project name>"
PROJECT_PATH="$GROUP_PATH/$PROJECT_NAME"
ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$PROJECT_PATH")"

For a link target in another project, use the same path-first shape instead of a numeric ID:

TARGET_PROJECT_PATH="<target namespace>/<target project>"
TARGET_ENCODED_PROJECT_PATH="$(node -e 'process.stdout.write(encodeURIComponent(process.argv[1]))' "$TARGET_PROJECT_PATH")"

Pass --hostname "$GITLAB_HOST" to every glab api call. The endpoint itself then pins the project, including directly after creating a repository when the current directory does not yet identify the new project.

GitHub continues to use an owner/repo slug; gh repo takes it positionally and rejects -R:

gh repo view --json nameWithOwner -q '.nameWithOwner'

---