Daf Git

---
name: daf-git
description: GitHub/GitLab issue operations (create, view, update, comments) with Markdown syntax reference and gh/glab CLI guide
user-invocable: true
argument-hint: "[ISSUE-NUMBER|owner/repo#number]"
---

Complete workflow for managing GitHub Issues and GitLab Issues in DevAIFlow.
Automatically detects the platform from your git repository.

## Quick Start

**View issue details (use gh/glab CLI directly):**
```bash
# GitHub
gh issue view 123 --json title,body,comments,labels,url

# GitLab
glab issue view 123
glab issue view 123 --comments
```

## All Commands

### Creating Issues

Use `gh` or `glab` CLI directly to create issues. The issue URL and key returned by
the CLI are the canonical record for the new ticket:

```bash
# GitHub
gh issue create --title "Add caching" --body "Description here" --label "enhancement"

# GitLab
glab issue create --title "Add caching" --description "Description here" --label "enhancement"
```

**After creating an issue in a `daf git new` session:**

- Include the issue URL and key in the final response.
- Do not attempt to associate the issue with the session using a DAF command.
  GitHub/GitLab ticket-creation sessions do not currently have a supported
  session-link operation.
- After leaving the agent session, reopen the ticket-creation session by the
  name printed by `daf git new`, for example: `daf open <session-name>`.

### Issue Body Templates

When creating issues with `daf git new`, templates are automatically injected into the prompt.
Templates come from (in priority order):
1. **Config templates** - `github_issue_templates` in organization.json/team.json
2. **Repo templates** - `.github/ISSUE_TEMPLATE/` (GitHub) or `.gitlab/issue_templates/` (GitLab)
3. **Built-in defaults** - Standard templates for bug, enhancement, task, epic

**Example structured issue body (bug):**

```markdown
## Bug Description

**What happened:**
API returns 500 when pagination limit exceeds 100

**Expected behavior:**
API should return 400 with validation error

**Steps to reproduce:**
1. Call GET /api/items?limit=200
2. Observe 500 Internal Server Error

## Environment
- Version: v2.3.1
- OS: Linux

## Acceptance Criteria
- [ ] Bug is fixed
- [ ] Regression test added
- [ ] No new issues introduced
```

**Configuring custom templates** in organization.json or team.json:

```json
{
  "github_issue_templates": {
    "bug": "## Bug Report\n\n**Symptoms:**\n...",
    "enhancement": "## Feature Request\n\n**Problem:**\n...",
    "task": "## Task\n\n**Objective:**\n..."
  }
}
```

### Viewing Issues

Use the `gh` or `glab` CLI directly to view issues:

```bash
# GitHub
gh issue view 123 --json title,body,comments,labels,url    # View issue
gh issue view 123 --repo owner/repo --json title,body,comments,labels,url

# GitLab
glab issue view 123                        # View issue
glab issue view 123 --comments            # Include comments
glab issue view 123 -R owner/repo         # Cross-repo
```

**Tip:** The issue key is available from `daf info` or `daf status`.

For a key in `owner/repo#123` form, split the key at the final `#` and pass the
repository explicitly. Run one lookup command only: a non-zero result should
be reported as an error, and empty issue fields in a successful response should
not trigger a retry with another repository or output format.

### Adding Comments

Use the `gh` or `glab` CLI directly to add comments:

```bash
# GitHub
gh issue comment 123 --body "Work in progress"

# GitLab
glab issue note 123 -m "Work in progress"
```

### daf git update
Update issue fields.

```bash
# Update labels
daf git update 123 --labels "priority: high,backend"

# Update assignee
daf git update 123 --assignee username

# Update milestone
daf git update 123 --milestone "v2.0"

# Update multiple fields
daf git update 123 --labels "critical" --assignee user --milestone "Sprint 5"

# Link to parent issue
daf git update 123 --parent "#456"
daf git update 123 --parent "owner/repo#789"
```

## GitHub/GitLab Markdown Syntax

**CRITICAL:** GitHub and GitLab issues use **Markdown syntax**, NOT JIRA Wiki markup.

When creating or updating GitHub/GitLab issues, all text fields (descriptions, comments) **MUST** use standard **Markdown** formatting.

### Syntax Reference

| Element | Markdown (CORRECT) | JIRA Wiki (WRONG) |
|---------|--------------------|--------------------|
| Header 2 | `## Header` | `h2. Header` |
| Header 3 | `### Header` | `h3. Header` |
| Bold | `**bold**` | `*bold*` |
| Italic | `*italic*` | `_italic_` |
| Code block | ` ```bash\ncode\n``` ` | `{code:bash}\ncode\n{code}` |
| Inline code | `` `code` `` | `{{code}}` |
| Unordered list | `- item` | `* item` |
| Ordered list | `1. item` | `# item` |
| Link | `[text](url)` | `[text\|url]` |
| Checkbox | `- [ ] item` | N/A |
| Checked box | `- [x] item` | N/A |

### When to Use Each Syntax

**Use Markdown for GitHub/GitLab operations:**
- `gh issue create` / `glab issue create` - Creating GitHub/GitLab issues
- `daf git update` / `gh issue edit` - Updating issue descriptions
- Pull request descriptions and comments

**Use JIRA Wiki markup for JIRA operations:**
- `daf jira create` / `daf jira add-comment` / `daf jira update`

## Ticket Creation Sessions

Create analysis-only sessions for creating GitHub/GitLab issues:

```bash
# Create ticket creation session (templates auto-injected into prompt)
daf git new enhancement --goal "Add caching layer"
daf git new bug --goal "Fix timeout in API"
daf git new task --goal "Refactor auth module" --parent "#123"
```

**Purpose:** Analyze the codebase to create a well-informed issue

**Template injection:** The prompt automatically includes issue body templates from config,
repo `.github/ISSUE_TEMPLATE/` directory, or built-in defaults. Use them to structure
well-formed issues with acceptance criteria.

**Constraints:**
- DO NOT modify code or files
- DO NOT run git commands
- ONLY read files, search code, analyze architecture
- Create the issue when analysis is complete using `gh issue create` /
  `glab issue create`, then report its URL and key

**See also:** daf-workflow skill for complete ticket creation workflow.

---

## GitHub Operations

### Authentication

```bash
# Interactive login
gh auth login

# Check status
gh auth status

# Token-based login
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
gh auth login --with-token < <(echo $GITHUB_TOKEN)
```

**Fine-grained tokens:** Some organizations require fine-grained tokens instead of classic tokens.

When you see: "forbids access via a personal access token (classic)":
1. Go to: https://github.com/settings/personal-access-tokens/new
2. Select "Only select repositories" and choose the specific repo
3. Grant permissions: Contents (R/W), Issues (R/W), Pull requests (R/W)
4. Authenticate: `gh auth login` and paste the token

**Pre-flight auth check:**
```bash
# GitHub
gh auth status

# GitLab
glab auth status
```

### PR Creation (daf complete pattern)

```bash
# Basic PR creation
gh pr create --draft --title "Title" --body "Description"

# Fork detection - create PR to upstream
gh pr create --draft --title "Title" --body "Description" --repo upstream-owner/upstream-repo

# Create PR with template
gh pr create --draft --title "PROJ-123: Feature" --body "$(cat <<'EOF'
## Description
...

Assisted-by: <actual AI assistant>
EOF
)"
```

**Fork detection:**
```bash
# Check if repository is a fork
gh repo view --json isFork,parent

# List remotes to see upstream
git remote -v
```

### Fetching Files from Private Repos

```bash
# Fetch file contents (raw)
gh api \
  -H "Accept: application/vnd.github.raw" \
  "/repos/owner/repo/contents/path/to/file"

# Fetch from specific branch
gh api \
  -H "Accept: application/vnd.github.raw" \
  "/repos/owner/repo/contents/path/to/file?ref=branch-name"

# Fetch PR template from organization .github repo
gh api \
  -H "Accept: application/vnd.github.raw" \
  "/repos/YOUR-ORG/.github/contents/.github/PULL_REQUEST_TEMPLATE.md"
```

---

## GitLab Operations

### Authentication

```bash
# Interactive login (GitLab.com)
glab auth login

# Self-hosted GitLab (full parameters)
glab auth login --hostname gitlab.example.com \
  --api-host gitlab.example.com \
  --api-protocol https \
  --git-protocol git \
  -t $GITLAB_TOKEN

# Check status
glab auth status
```

**Token:** Create at GitLab Settings > Access Tokens with `api` scope.

### MR Creation (daf complete pattern)

```bash
# Basic MR creation
glab mr create --draft --title "Title" --description "Description"

# Fork detection - create MR to upstream
glab mr create --draft \
  --title "Title" \
  --description "Description" \
  --target-project upstream-group/upstream-repo

# Create MR to specific target branch
glab mr create --target-branch develop --title "Title" --description "Body"
```

**Fork detection:**
```bash
# Check if project is a fork
glab repo view -F json | jq '.forked_from_project'

# List remotes to see upstream
git remote -v
```

### Fetching Files from Private Repos

```bash
# Fetch file contents (raw) - URL encode paths with %2F
glab api "projects/group%2Fproject/repository/files/path%2Fto%2Ffile/raw?ref=main"

# Multi-level groups
glab api "projects/group%2Fsubgroup%2Fproject/repository/files/README.md/raw?ref=main"
```

---

## gh vs glab Syntax Differences

| Operation | GitHub (`gh`) | GitLab (`glab`) |
|-----------|---------------|-----------------|
| JSON output | `--json` | `-F json` (NOT `--json`) |
| Create PR/MR | `gh pr create --body` | `glab mr create --description` |
| Fork target | `--repo owner/repo` | `--target-project group/repo` |
| Hostname | N/A (default) | `--hostname` (auth only, NEVER in mr create) |
| Check MR | `gh pr list --head branch` | `glab mr list -F json \| jq` |
| Ready for review | `gh pr ready 123` | `glab mr update 123 --ready` |
| Approve | `gh pr review 123 --approve` | `glab mr approve 123` |

**Common mistakes:**
- Using `--json` with glab (use `-F json`)
- Using `--body` with glab mr create (use `--description`)
- Using `--hostname` with glab mr create (only for `glab auth login`)

## PR/MR Template

Standard template used by daf tool:

```markdown
## Description

[Brief description of changes]

## Testing

### Steps to test
1. Pull down the PR/MR
2. [Add specific test steps]

### Scenarios tested
- [ ] Test scenario 1
- [ ] Test scenario 2

## Deployment considerations
- [ ] This code change is ready for deployment on its own
- [ ] This code change requires considerations before being deployed:

Assisted-by: <actual AI assistant>
```

**GitLab addition:** Add `Jira Issue: https://jira.example.com/browse/PROJ-XXXXX` at the top if using JIRA.

## GitHub/GitLab vs JIRA

**Key differences:**
- **Issue types**: Uses labels (bug, enhancement, task) instead of native JIRA types
- **Priority**: Convention-based labels (`priority: high`, `priority: critical`)
- **Story points**: Labels (`points: 3`, `points: 5`, `points: 8`)
- **Workflows**: Binary state (open/closed) + optional status labels
- **Sprints**: Uses milestones instead
- **Attachments**: GitHub doesn't support files, GitLab does

## Platform Detection

DevAIFlow automatically detects GitHub vs GitLab from:
1. Git remote URL (github.com vs gitlab.com)
2. Issue key format
3. Repository configuration

Both platforms use `#` format for issues:
- `#123` - Issue in current repository
- `owner/repo#123` - Issue in specific repository

## Requirements

- **GitHub**: GitHub CLI (`gh`) installed and authenticated (`gh auth login`)
- **GitLab**: GitLab CLI (`glab`) installed and authenticated (`glab auth login`)

## Typical Workflows

**Working on existing issue:**
```bash
# 1. View issue details
gh issue view 456 --json title,body,comments,labels,url    # GitHub
# or: glab issue view 456 --comments                              # GitLab

# 2. Add status comment (use gh/glab directly)
gh issue comment 456 --body "Started implementation"    # GitHub
glab issue note 456 -m "Started implementation"         # GitLab

# 3. Work on implementation...
```

**Create issue without session:**
```bash
# GitHub
gh issue create --title "Refactor auth module" --assignee teammate --label "refactor,backend"

# GitLab
glab issue create --title "Refactor auth module" --assignee teammate --label "refactor,backend"
```