Git Platform

Table of Contents

• Overview
• When to Use
• Platform Detection
• Quick Command Reference
• Terminology
• Integration Pattern
• Detailed Resources
• Exit Criteria

Git Platform Detection & Command Mapping

Overview

Cross-platform abstraction for git forge operations. Detects whether the current project uses GitHub, GitLab, or Bitbucket, and provides equivalent CLI commands for each platform.

The SessionStart hook (detect-git-platform.sh) automatically injects the detected platform into session context. This skill provides the command reference for translating operations across platforms.

When To Use

• Before running gh, glab, or forge API commands
• When a skill or command needs to create issues, PRs/MRs, or post comments
• When writing CI/CD configuration
• Any time forge-specific CLI commands appear in a workflow

When NOT To Use

• Local-only git operations (git commit, git branch, etc.)
• Projects without a hosted git remote

Platform Detection

Detection is automatic via the SessionStart hook. The session context will contain:

git_platform: github|gitlab|bitbucket, cli: gh|glab, mr_term: pull request|merge request

If you need to re-detect manually:

# Check remote URL
git remote get-url origin 2>/dev/null

# Check file markers
ls -d .github/ .gitlab-ci.yml bitbucket-pipelines.yml 2>/dev/null

# Check CLI availability
command -v gh && echo "GitHub CLI available"
command -v glab && echo "GitLab CLI available"

Quick Command Reference

For Bitbucket: No standard CLI exists. Use REST API (curl) or the web interface. See command-mapping module for API equivalents.

Terminology

Important: When the platform is GitLab, always say "merge request" (not "pull request") in user-facing output, commit messages, and comments.

Integration Pattern

Skills that perform forge operations should:

1. Declare dependencies: [leyline:git-platform] 2. Check the session context for git_platform: 3. Use the command mapping table above 4. Fall back gracefully if CLI is unavailable

# Example skill instruction pattern:

## Step N: Create PR/MR

Use the detected platform CLI (check session context for `git_platform`):
- **GitHub**: `gh pr create --title "..." --body "..."`
- **GitLab**: `glab mr create --title "..." --description "..."`
- **Bitbucket**: Create via web interface

Detailed Resources

• Full command mapping: See modules/command-mapping.md for complete API equivalents, GraphQL queries, and Bitbucket REST API patterns
• Authentication: See Skill(leyline:authentication-patterns) for ensure_auth github|gitlab

Exit Criteria

• Platform detected (or explicitly unknown)
• Correct CLI tool used for all forge operations
• Platform-appropriate terminology in user-facing output

Complete Command Mapping

Full cross-platform command equivalents for forge operations.

Issue Operations

PR/MR Operations

GraphQL Operations

GitHub

gh api graphql -f query='
query {
  repository(owner: "OWNER", name: "REPO") {
    pullRequest(number: N) {
      reviewThreads(first: 100) {
        nodes { id isResolved path }
      }
    }
  }
}'

GitLab

glab api graphql -f query='
query {
  project(fullPath: "OWNER/REPO") {
    mergeRequest(iid: "N") {
      discussions { nodes { id resolved notes { nodes { body } } } }
    }
  }
}'

CI/CD Configuration

Repo Metadata

Discussion Operations

Platform support: GitHub only (via GraphQL API). GitLab and Bitbucket do not have equivalent Discussion features. All operations below will be skipped with a warning on non-GitHub platforms.

Prerequisites

Before running any Discussion operation, resolve the repository ID and verify Discussions are enabled:

# Get repository node ID (required for createDiscussion)
gh api graphql -f query='
query($owner: String!, $repo: String!) {
  repository(owner: $owner, name: $repo) {
    id
    hasDiscussionsEnabled
  }
}' -f owner="OWNER" -f repo="REPO"

Category Resolution

Discussion mutations require a category nodeId. Resolve from slug:

# List all discussion categories (slug → nodeId mapping)
gh api graphql -f query='
query($owner: String!, $repo: String!) {
  repository(owner: $owner, name: $repo) {
    discussionCategories(first: 25) {
      nodes { id name slug description }
    }
  }
}' -f owner="OWNER" -f repo="REPO"

CRUD Operations

Create Discussion

gh api graphql -f query='
mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
  createDiscussion(input: {
    repositoryId: $repoId,
    categoryId: $categoryId,
    title: $title,
    body: $body
  }) {
    discussion { number id url }
  }
}' -f repoId="$REPO_ID" -f categoryId="$CATEGORY_ID" -f title="$TITLE" -f body="$BODY"

Add Comment

gh api graphql -f query='
mutation($discussionId: ID!, $body: String!) {
  addDiscussionComment(input: {
    discussionId: $discussionId,
    body: $body
  }) {
    comment { id url }
  }
}' -f discussionId="$DISCUSSION_ID" -f body="$COMMENT_BODY"

To reply to a specific comment (threaded):

gh api graphql -f query='
mutation($discussionId: ID!, $replyToId: ID!, $body: String!) {
  addDiscussionComment(input: {
    discussionId: $discussionId,
    body: $body,
    replyToId: $replyToId
  }) {
    comment { id url }
  }
}' -f discussionId="$DISCUSSION_ID" -f replyToId="$PARENT_COMMENT_ID" -f body="$REPLY_BODY"

Mark as Answer

Only works on Q&A category discussions:

gh api graphql -f query='
mutation($commentId: ID!) {
  markDiscussionCommentAsAnswer(input: {
    id: $commentId
  }) {
    discussion { id answerChosenAt }
  }
}' -f commentId="$COMMENT_ID"

Search Discussions

Search by keyword, category, and/or label:

gh api graphql -f query='
query($searchQuery: String!) {
  search(query: $searchQuery, type: DISCUSSION, first: 10) {
    discussionCount
    nodes {
      ... on Discussion {
        number
        title
        url
        createdAt
        category { name slug }
        labels(first: 5) { nodes { name } }
        answer { id body }
      }
    }
  }
}' -f searchQuery="repo:OWNER/REPO category:decisions SEARCH_TERMS"

Search query syntax supports: repo:, category:, label:, author:, is:answered, is:unanswered, plus free-text keywords.

Get Discussion

gh api graphql -f query='
query($owner: String!, $repo: String!, $number: Int!) {
  repository(owner: $owner, name: $repo) {
    discussion(number: $number) {
      id
      title
      body
      createdAt
      category { name slug }
      labels(first: 10) { nodes { name } }
      answer { id body author { login } }
      comments(first: 20) {
        nodes {
          id
          body
          author { login }
          createdAt
          isAnswer
        }
      }
    }
  }
}' -f owner="OWNER" -f repo="REPO" -F number=NUMBER

Note: Use -F (not -f) for integer variables.

Update Discussion

gh api graphql -f query='
mutation($discussionId: ID!, $body: String!) {
  updateDiscussion(input: {
    discussionId: $discussionId,
    body: $body
  }) {
    discussion { id url updatedAt }
  }
}' -f discussionId="$DISCUSSION_ID" -f body="$UPDATED_BODY"

List Recent Discussions by Category

Bounded query for listing recent discussions. The fetch-recent-discussions.sh SessionStart hook uses first: 5 for token budget compliance; adjust the limit as needed for other use cases:

gh api graphql -f query='
query($owner: String!, $repo: String!, $categoryId: ID!) {
  repository(owner: $owner, name: $repo) {
    discussions(first: 5, categoryId: $categoryId, orderBy: {field: CREATED_AT, direction: DESC}) {
      nodes {
        number
        title
        url
        createdAt
        body
        labels(first: 5) { nodes { name } }
      }
    }
  }
}' -f owner="OWNER" -f repo="REPO" -f categoryId="$CATEGORY_ID"