get_branches
Retrieve Git branches for version-controlled projects in Octopus Deploy spaces. Filter branches by name and manage results with pagination for efficient project management.
Instructions
Get Git branches for a version-controlled project
This tool retrieves Git branches for a specific project in a space. The space name and project ID are required. Optionally provide searchByName, skip, and take parameters for filtering and pagination.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | ||
| searchByName | No | ||
| skip | No | ||
| spaceName | Yes | ||
| take | No |
Implementation Reference
- src/tools/getBranches.ts:25-57 (handler)The main handler function for the 'get_branches' tool. It creates an Octopus client, resolves the space ID, calls the getProjectBranches helper, and returns the formatted JSON response.async ({ spaceName, projectId, searchByName, skip, take }) => { const configuration = getClientConfigurationFromEnvironment(); const client = await Client.create(configuration); const spaceId = await resolveSpaceId(client, spaceName); const options = { searchByName, skip, take, }; const branches = await getProjectBranches(client, spaceId, projectId, options); return { content: [ { type: "text", text: JSON.stringify({ Items: branches.Items.map(branch => ({ Name: branch.Name, IsProtected: branch.IsProtected, CanonicalName: branch.CanonicalName, })), TotalResults: branches.TotalResults, ItemsPerPage: branches.ItemsPerPage, NumberOfPages: branches.NumberOfPages, LastPageNumber: branches.LastPageNumber, ItemType: branches.ItemType, }), }, ], }; }
- src/tools/getBranches.ts:15-20 (schema)Zod input schema defining parameters for the get_branches tool: spaceName, projectId, and optional pagination/filtering.spaceName: z.string(), projectId: z.string(), searchByName: z.string().optional(), skip: z.number().optional(), take: z.number().optional(), },
- src/tools/getBranches.ts:8-59 (registration)Primary registration of the 'get_branches' tool using server.tool, including name, description, schema, metadata, and handler.export function registerGetBranchesTool(server: McpServer) { server.tool( "get_branches", `Get Git branches for a version-controlled project This tool retrieves Git branches for a specific project in a space. The space name and project ID are required. Optionally provide searchByName, skip, and take parameters for filtering and pagination.`, { spaceName: z.string(), projectId: z.string(), searchByName: z.string().optional(), skip: z.number().optional(), take: z.number().optional(), }, { title: "Get Git branches for a version-controlled project", readOnlyHint: true, }, async ({ spaceName, projectId, searchByName, skip, take }) => { const configuration = getClientConfigurationFromEnvironment(); const client = await Client.create(configuration); const spaceId = await resolveSpaceId(client, spaceName); const options = { searchByName, skip, take, }; const branches = await getProjectBranches(client, spaceId, projectId, options); return { content: [ { type: "text", text: JSON.stringify({ Items: branches.Items.map(branch => ({ Name: branch.Name, IsProtected: branch.IsProtected, CanonicalName: branch.CanonicalName, })), TotalResults: branches.TotalResults, ItemsPerPage: branches.ItemsPerPage, NumberOfPages: branches.NumberOfPages, LastPageNumber: branches.LastPageNumber, ItemType: branches.ItemType, }), }, ], }; } ); }
- src/tools/getBranches.ts:61-66 (registration)Registers the tool definition in the TOOL_REGISTRY for conditional enabling via toolsets.registerToolDefinition({ toolName: "get_branches", config: { toolset: "context", readOnly: true }, registerFn: registerGetBranchesTool, minimumOctopusVersion: "2021.2", });
- Supporting helper function that performs the actual API call to retrieve Git branches for a project from Octopus Deploy.export async function getProjectBranches( client: Client, spaceId: string, projectId: string, options?: GetProjectBranchesOptions ): Promise<ResourceCollection<GitBranch>> { const queryParams: Record<string, string> = {}; if (options?.searchByName) { queryParams.searchByName = options.searchByName; } if (options?.skip !== undefined) { queryParams.skip = options.skip.toString(); } if (options?.take !== undefined) { queryParams.take = options.take.toString(); } const result = await client.get<ResourceCollection<GitBranch>>( "~/api/{spaceId}/projects/{projectId}/git/branches{?skip,take,searchByName}", { spaceId, projectId, ...queryParams, }, ); return result; }