Git Agent

The git agent handles git provider operations within a workflow. Currently it supports creating pull requests on GitHub or Bitbucket. It auto-detects the provider from the repository’s remote URL, or you can set it explicitly in settings.

Use this agent for the finalization phase of a workflow — after implementation and review, create a PR with a single phase declaration. The git agent also supports event-driven PR creation via its notify handler, eliminating the need for a dedicated finalize phase.

---

Sample Phase

- name: finalize
  agent: git
  action: create_pr
  depends_on: [review]

---

Phase Configuration

Actions

Action	Description
create_pr	Create a pull request on the detected provider. Fails if a PR already exists for the current branch.

Phase YAML Fields

Field	Type	Required	Description
name	string	Yes	Unique phase name within the workflow
type	string	No	Defaults to "standard"
agent	string	Yes	Must be "git"
depends_on	string[]	No	Upstream phases that must complete before this phase runs
action	string	Yes	Currently only "create_pr" is supported
notify	object	No	Event-driven handler (e.g., create PR on pipeline complete)

Notify Handler

The git agent supports event-driven PR creation via the notify block. Attach it to any phase to trigger automatic PR creation without a dedicated finalize phase:

notify:
    on_complete:
        action: create_pr

Supported events: on_complete.

---

Settings

Configure under agents.git in settings.json (via cliq setup or cliq settings):

Provider Detection

Key	Required	Default	Description
agents.git.provider	No	(auto-detected)	Force a provider: "github" or "bitbucket"

Provider auto-detection: URLs containing bitbucket.org use Bitbucket; everything else uses GitHub.

GitHub

Key	Required	Default	Description
agents.git.github.token	Yes	—	GitHub Personal Access Token
agents.git.github.base_branch	No	"main"	Branch to create feature branches from
agents.git.github.remote	No	"origin"	Git remote name
agents.git.github.branch_prefix	No	"cliq/"	Prefix for feature branches
agents.git.github.pr_draft	No	false	Create PRs as drafts
agents.git.github.pr_reviewers	No	[]	GitHub usernames to request review from
agents.git.github.pr_labels	No	["cliq-generated"]	Labels to apply to created PRs

Bitbucket

Key	Required	Default	Description
agents.git.bitbucket.workspace	Yes	—	Bitbucket workspace slug
agents.git.bitbucket.email	Yes	—	Atlassian account email
agents.git.bitbucket.api_token	Yes	—	Bitbucket API token (Repos R/W + PRs R/W)

---

Output

Handoff Structure

{
    "data": {
        "action": "create_pr",
        "url": "https://github.com/acme/webapp/pull/42",
        "id": 42,
        "pr_created": true
    },
    "text": "PR created: https://github.com/acme/webapp/pull/42"
}

Field Reference

Field	Location	Description
action	data.action	The action that was performed
url	data.url	Full URL to the created pull request
id	data.id	PR number (GitHub) or PR ID (Bitbucket)
pr_created	data.pr_created	true if a new PR was created

Downstream Access

commands:
    - name: announce
      run: 'echo "PR available at $(handoff.finalize.data.url)"'

---

Examples

Example: Create PR after implementation and review

The standard finalization pattern — implement, review, then create a PR.

phases:
    - name: implement
      agent: cursor

    - name: review
      type: gate
      agent: hug
      depends_on: [implement]
      review:
          reviewer: tech-lead
          artifacts:
              - src/**/*.ts

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [review]

Example: Event-driven PR creation via notify

Skip the dedicated finalize phase — create a PR automatically when implementation completes.

phases:
    - name: implement
      agent: cursor
      notify:
          on_complete:
              action: create_pr

    - name: review
      type: gate
      agent: hug
      depends_on: [implement]
      review:
          reviewer: tech-lead

Example: Multi-phase pipeline with Bitbucket

A full pipeline targeting a Bitbucket repository.

phases:
    - name: fetch-ticket
      agent: jira
      action: get_issue
      sources:
          - name: ticket.json
            ref: PROJ-456

    - name: implement
      agent: cursor
      depends_on: [fetch-ticket]

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [implement]

---

Setup

GitHub

1. Go to https://github.com/settings/tokens
2. Click Generate new token → Fine-grained token (recommended)
3. Name it (e.g., cliq), set expiration, and scope to your repositories
4. Under Permissions → Repository permissions, grant:

Permission	Level	Why
Contents	Read and write	Push commits and branches
Pull requests	Read and write	Create PRs, add reviewers

5. Click Generate token and copy it

Classic tokens also work — select the repo scope.

echo $GITHUB_TOKEN | cliq settings agents.git.github.token --stdin --global
cliq settings agents.git.github.base_branch main --global
cliq doctor agent git

Bitbucket

1. Find your workspace slug from your repo URL: https://bitbucket.org/<workspace>/<repo>
2. Note your Atlassian account email from https://bitbucket.org/account/settings/
3. Go to https://bitbucket.org/account/settings/app-passwords/ and create a token with:

Category	Level	Why
Repositories	Read + Write	Push commits and branches
Pull requests	Read + Write	Create and merge PRs

In Bitbucket, Write does NOT imply Read. Check both for each category.

cliq settings agents.git.bitbucket.workspace my-workspace --global
cliq settings agents.git.bitbucket.email [email protected] --global
echo $BB_TOKEN | cliq settings agents.git.bitbucket.api_token --stdin --global
cliq doctor agent git

Validation

cliq doctor agent git checks:

• git binary is on PATH
• Provider credentials are configured
• Credentials can authenticate against the provider API

---

See Also

• Agent Overview