createPullRequest

Create a pull request after generating code changes.

Method signature

async createPullRequest(
  repository: string,
  labelOptions?: LabelOptions,
  branchPrefix?: string
): Promise<PullRequestResponse>

Description

The createPullRequest method allows you to create a GitHub pull request after code changes have been generated using any supported agent (Codex, Claude, OpenCode, or Gemini). This method streamlines the process of submitting code changes for review by automatically creating a pull request with the generated modifications.

Parameters

Parameter	Type	Required	Description
repository	string	Yes	The GitHub repository in format “owner/repo”
labelOptions	LabelOptions	No	Optional label configuration for the pull request
branchPrefix	string	No	Optional prefix for the branch name that will be created

LabelOptions Interface

Property	Type	Required	Description
name	string	Yes	The name of the label to create/apply to the pull request
color	string	Yes	The color of the label in hex format (without #). Examples: “0e8a16” (green), “d73a49” (red), “0366d6” (blue)
description	string	Yes	A description of what this label represents

Return type

Type	Description
Promise<PullRequestResponse>	Promise that resolves to a pull request response object

PullRequestResponse Interface

Property	Type	Required	Description
id	number	Yes	The unique identifier of the pull request
number	number	Yes	The pull request number
state	string	Yes	The state of the pull request (e.g., “open”, “closed”)
title	string	Yes	The title of the pull request
body	string	Yes	The body/description of the pull request
html_url	string	Yes	The URL to view the pull request on GitHub
head	object	Yes	Information about the head branch of the PR
base	object	Yes	Information about the base branch of the PR
user	object	Yes	Information about the user who created the PR
created_at	string	Yes	ISO timestamp when the PR was created
updated_at	string	Yes	ISO timestamp when the PR was last updated
merged	boolean	Yes	Whether the pull request has been merged
mergeable	boolean | null	Yes	Whether the pull request can be merged
merge_commit_sha	string | null	Yes	The SHA of the merge commit if merged
branchName	string	Yes	The name of the branch created for the PR
commitSha	string	No	The SHA of the commit

Requirements

• Agent Type: This method is available for all supported agents (Codex, Claude, OpenCode, and Gemini)
• Initialization: The VibeKit instance must be properly initialized with valid agent configuration
• Code Generation: Code changes should be generated before creating a pull request
• GitHub Integration: A valid GitHub token must be configured using withSecrets({ GH_TOKEN: "your_token" })
• Repository Access: The provided GitHub token must have access to the specified repository

Error handling

The method throws errors in the following scenarios:

Initialization Error

throw new Error("Agent not initialized")

• When: The agent is not properly initialized
• Resolution: Verify your VibeKit configuration includes valid agent settings and GitHub configuration

Usage examples

Basic Usage

import { VibeKit } from 'vibekit';
import { createE2BProvider } from "@vibe-kit/e2b";

const e2bProvider = createE2BProvider({
  apiKey: process.env.E2B_API_KEY!,
});

const vibekit = new VibeKit()
  .withAgent({
    type: "claude",
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-sonnet-4-20250514",
  })
  .withSandbox(e2bProvider)
  .withSecrets({
    GH_TOKEN: process.env.GITHUB_TOKEN!,
  });

// Clone repository first
await vibekit.cloneRepository("your-org/your-repo");

// Generate code changes
await vibekit.generateCode({
  prompt: "Add a new user registration feature",
  mode: "code"
});

// Create pull request with default settings
try {
  const prResponse = await vibekit.createPullRequest("your-org/your-repo");
  
  console.log(`Pull request created: ${prResponse.html_url}`);
  console.log(`PR ID: ${prResponse.id}`);
  console.log(`PR Number: ${prResponse.number}`);
  console.log(`Title: ${prResponse.title}`);
  console.log(`State: ${prResponse.state}`);
  console.log(`Branch: ${prResponse.branchName}`);
  console.log(`Commit SHA: ${prResponse.commitSha}`);
  console.log(`Created at: ${prResponse.created_at}`);
  console.log(`Mergeable: ${prResponse.mergeable}`);
} catch (error) {
  console.error("Failed to create pull request:", error.message);
}

Advanced Usage with Parameters

import { VibeKit, LabelOptions } from 'vibekit';
import { createE2BProvider } from "@vibe-kit/e2b";

const e2bProvider = createE2BProvider({
  apiKey: process.env.E2B_API_KEY!,
});

const vibekit = new VibeKit()
  .withAgent({
    type: "claude",
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
    model: "claude-sonnet-4-20250514",
  })
  .withSandbox(e2bProvider)
  .withSecrets({
    GH_TOKEN: process.env.GITHUB_TOKEN!,
  });

// Clone repository first
await vibekit.cloneRepository("your-org/your-repo");

// Generate code changes
await vibekit.generateCode({
  prompt: "Add authentication middleware",
  mode: "code"
});

// Create pull request with custom parameters
const labelOptions: LabelOptions = {
  name: "ai-generated",
  color: "0e8a16",
  description: "Code generated by AI agent"
};

try {
  const prResponse = await vibekit.createPullRequest(
    "your-org/your-repo",       // Repository parameter (required)
    labelOptions,               // Custom label options
    "feature"                   // Branch prefix (will create feature/xyz branch)
  );
  
  console.log(`Pull request created: ${prResponse.html_url}`);
  console.log(`PR Number: ${prResponse.number}`);
  console.log(`Branch: ${prResponse.branchName}`);
  
  // Access additional GitHub API data
  console.log(`PR Title: ${prResponse.title}`);
  console.log(`PR Body: ${prResponse.body}`);
  console.log(`Author: ${prResponse.user.login}`);
  console.log(`Head branch: ${prResponse.head.ref}`);
  console.log(`Base branch: ${prResponse.base.ref}`);
} catch (error) {
  console.error("Failed to create pull request:", error.message);
}

Additional Label Examples

// Different label configurations
const bugfixLabel: LabelOptions = {
  name: "bug-fix",
  color: "d73a49",
  description: "Fixes a bug in the codebase"
};

const featureLabel: LabelOptions = {
  name: "new-feature",
  color: "0366d6", 
  description: "Adds new functionality"
};

const refactorLabel: LabelOptions = {
  name: "refactor",
  color: "f9d71c",
  description: "Code refactoring without functional changes"
};

Using with Different Agents

// Works with any agent type
const vibekitClaude = new VibeKit()
  .withAgent({ type: "claude", provider: "anthropic", model: "claude-sonnet-4-20250514", apiKey: "..." })
  .withSecrets({ GH_TOKEN: process.env.GITHUB_TOKEN })
  .withSandbox(sandbox);

const vibekitCodex = new VibeKit()
  .withAgent({ type: "codex", provider: "openai", model: "codex-mini-latest", apiKey: "..." })
  .withSecrets({ GH_TOKEN: process.env.GITHUB_TOKEN })
  .withSandbox(sandbox);

// Both agents support createPullRequest (now requires repository parameter)
await vibekitClaude.cloneRepository("your-org/your-repo");
await vibekitClaude.createPullRequest("your-org/your-repo");

await vibekitCodex.cloneRepository("your-org/your-repo");
await vibekitCodex.createPullRequest("your-org/your-repo");

Notes

• The pull request is automatically labeled with the agent type (‘codex’, ‘claude’, ‘opencode’, or ‘gemini’) to indicate which agent created it
• Ensure your GitHub token has the necessary permissions to create pull requests in the target repository
• The method creates a new branch for the pull request automatically
• Code changes must be generated before calling this method
• Repository must be explicitly cloned using cloneRepository() before generating code
• When using branchPrefix, the final branch name will be in the format {branchPrefix}/{generated-suffix}
• The labelOptions parameter creates a new label if it doesn’t exist in the repository and applies it to the pull request
• The response includes the complete GitHub API pull request data, allowing access to detailed information like user details, branch information, timestamps, and merge status
• The repository parameter is now required and specifies which repository to create the pull request in