Forge Concept Commands

Forge concept commands decouple codev from direct gh CLI calls. Each GitHub operation is routed through a configurable external command.

Concepts

Concept	Env Vars	Description
issue-view	CODEV_ISSUE_ID	Fetch issue details (JSON)
pr-list	—	List open PRs (JSON array)
issue-list	—	List issues (JSON array)
issue-comment	CODEV_ISSUE_ID, CODEV_COMMENT_BODY	Post a comment on an issue
pr-exists	CODEV_BRANCH_NAME	Check if a PR exists for a branch
recently-closed	CODEV_SINCE_DATE (optional)	List recently closed issues
recently-merged	CODEV_SINCE_DATE (optional)	List recently merged PRs
user-identity	—	Get current user's handle (plain text)
team-activity	CODEV_GRAPHQL_QUERY	Run a batched GraphQL query
on-it-timestamps	CODEV_ISSUE_NUMBERS, CODEV_GRAPHQL_QUERY, CODEV_REPO_OWNER, CODEV_REPO_NAME	Get "on it" comment timestamps
pr-create	CODEV_PR_TITLE, CODEV_PR_BODY, CODEV_PR_BASE (optional), CODEV_PR_HEAD (optional), CODEV_PR_REPO (optional), CODEV_PR_DRAFT (optional)	Open a PR; prints {"number", "url"}
pr-merge	CODEV_PR_NUMBER	Merge a PR
pr-search	CODEV_SEARCH_QUERY	Search PRs (JSON array)
pr-view	CODEV_PR_NUMBER, CODEV_INCLUDE_COMMENTS (optional)	View PR details (JSON or text)
pr-diff	CODEV_PR_NUMBER, CODEV_DIFF_NAME_ONLY (optional)	Get PR diff
auth-status	—	Check forge authentication status

Configuration

In .codev/config.json:

{
  "forge": {
    "provider": "gitlab",
    "issue-comment": "my-custom-script $CODEV_ISSUE_ID"
  }
}

Resolution order

1. Manual concept override in forge section
2. Provider preset (if provider is set)
3. Default (GitHub via gh CLI)

Providers

Built-in presets: github (default), gitlab (via glab), gitea (via tea).

Note: Non-GitHub presets are best-effort. Output schemas may differ from GitHub's JSON contracts. Non-conforming JSON returns null — consumers handle this gracefully. Override individual concepts if a preset doesn't match your CLI version.

CODEV_REPO is overloaded. For repo-archive it is an input: the owner/repo to download. For the Gitea preset's read concepts (pr-view, pr-list, pr-exists, issue-view, recently-merged) it is an override — tea api needs an explicit owner/repo in the endpoint path, which those scripts otherwise derive from the origin remote. Set it per invocation, not in your environment: exported globally it retargets every Gitea read at that repo.

Disabling concepts

Set a concept to null to disable it:

{
  "forge": {
    "team-activity": null
  }
}

Validation

Run codev doctor to see forge concept status, provider, and validation results.

Code

• Dispatcher: packages/codev/src/lib/forge.ts
• Contracts: packages/codev/src/lib/forge-contracts.ts
• Spec: codev/specs/589-non-github-repository-support.md