Documentation Index
Fetch the complete documentation index at: https://docs.vibekit.sh/llms.txt
Use this file to discover all available pages before exploring further.
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
