SDKs overview

Buddy provides various tools, including official SDKs and community-contributed libraries, to facilitate programmatic interaction with its CI/CD platform. These resources enable developers to automate tasks such as pipeline definition, project management, and execution monitoring directly from their codebases or scripts. Utilizing an SDK can streamline the integration of Buddy into existing development workflows, allowing for custom automation beyond the visual interface Buddy offers. The official SDKs are designed to interact with the Buddy API endpoints, which support actions like creating and updating projects, managing pipelines, and deploying code. This extensibility is crucial for organizations that require deep integration with their internal systems or have complex, multi-stage deployment processes.

The SDKs abstract the underlying HTTP requests and authentication mechanisms, providing a more convenient and language-idiomatic way to use the Buddy API. This simplifies development by handling serialization, deserialization, and error handling, allowing developers to focus on the logic of their automation scripts. For example, an SDK might offer methods to trigger a specific pipeline, retrieve the status of a past execution, or even dynamically adjust environment variables for a deployment. This level of control is particularly useful for implementing GitOps practices or integrating Buddy with other developer tools like issue trackers or notification services. Community libraries often build upon these official interfaces, adding specialized functionalities or supporting languages not covered by the official offerings. These contributions demonstrate the flexibility and open nature of Buddy's platform, encouraging broader adoption and custom solutions.

Official SDKs by language

Buddy maintains official SDKs to provide robust and supported interfaces for interacting with its platform. These SDKs are typically developed and maintained by the Buddy team, ensuring compatibility with the latest API versions and features. They are designed to offer a consistent and reliable experience for developers, abstracting the complexities of direct API calls into more manageable function calls. The primary official SDKs available focus on widely used programming languages, enabling a broad range of developers to integrate Buddy into their projects.

Language Package Install Command Maturity
Python buddy-cli pip install buddy-cli Stable
Node.js @buddyrun/sdk npm install @buddyrun/sdk Stable

The Python buddy-cli package, while primarily a command-line interface, also offers programmatic access to the Buddy API, making it suitable for scripting and automation within Python applications. Similarly, the Node.js SDK provides a JavaScript/TypeScript interface for web-based applications or server-side Node.js environments. These SDKs handle authentication, request formatting, and response parsing, reducing the boilerplate code developers need to write. Developers can find detailed documentation for these official SDKs, including API references and usage examples, on the Buddy API documentation page.

Installation

Installing Buddy's official SDKs typically involves using standard package managers for the respective programming languages. This ensures that dependencies are correctly managed and that the SDK can be easily integrated into existing projects. Before installation, developers should ensure they have the correct runtime environment set up, such as Python 3.x for the Python CLI or Node.js 12+ for the Node.js SDK.

Python CLI Installation

To install the Python-based Buddy CLI, which also serves as a programmatic interface, use pip:

pip install buddy-cli

After installation, you can verify the installation by running buddy --version. The CLI requires an API key for authentication, which can be generated within the Buddy dashboard under your profile settings. This key is then configured through the CLI or set as an environment variable.

Node.js SDK Installation

For Node.js projects, the official SDK can be installed via npm:

npm install @buddyrun/sdk

Alternatively, if you are using Yarn:

yarn add @buddyrun/sdk

Once installed, the SDK can be imported into your Node.js application. Similar to the Python CLI, the Node.js SDK requires an API key for authentication. This key should be kept secure and ideally loaded from environment variables or a secure configuration store rather than hardcoded directly into the application. For more detailed instructions on setting up authentication, refer to the Buddy API authentication guide.

Quickstart example

This quickstart example demonstrates how to use the Node.js SDK to list projects within your Buddy account. Before running this code, ensure you have installed the Node.js SDK and have a valid Buddy API key available, ideally as an environment variable.

const { Buddy } = require('@buddyrun/sdk');

// Initialize the Buddy SDK with your API key
// It's recommended to load the API key from environment variables
const buddy = new Buddy(process.env.BUDDY_API_KEY);

async function listBuddyProjects() {
  try {
    // Fetch a list of all projects accessible by the API key
    const projects = await buddy.api.workspace.projects.list();

    console.log('Buddy Projects:');
    if (projects.length === 0) {
      console.log('No projects found.');
      return;
    }

    projects.forEach(project => {
      console.log(`- ${project.name} (ID: ${project.id})`);
    });
  } catch (error) {
    console.error('Error listing projects:', error.message);
    // Log specific details from the error response if available
    if (error.response && error.response.data) {
      console.error('API Error Details:', error.response.data);
    }
  }
}

// Execute the function
listBuddyProjects();

To run this example:

  1. Save the code as listProjects.js.
  2. Set your Buddy API key as an environment variable: export BUDDY_API_KEY='your_api_key_here' (on Linux/macOS) or $env:BUDDY_API_KEY='your_api_key_here' (on PowerShell).
  3. Execute from your terminal: node listProjects.js.

This script will connect to the Buddy API using your provided key and output a list of project names and their corresponding IDs. This basic example can be extended to perform more complex operations, such as triggering pipelines, creating new projects, or managing deployments, by exploring the full range of methods available in the Buddy API reference documentation.

Community libraries

While Buddy provides official SDKs for popular languages, the open nature of its API encourages the development of community-contributed libraries. These libraries often fill gaps in language support, offer specialized functionalities, or integrate Buddy with other tools in novel ways. Community contributions can range from simple wrappers around the HTTP API to comprehensive frameworks for managing complex CI/CD workflows.

Developers often publish these libraries on public package repositories like GitHub, npm, or PyPI. Before using a community library, it is advisable to assess its maintenance status, documentation quality, and community support. Reviewing the source code and checking for recent updates and active issues can provide insight into its reliability and future viability. For example, a community library might provide a Go client for Buddy's API, allowing Go developers to manage their CI/CD pipelines natively within their Go applications without resorting to executing external commands or writing raw HTTP requests. Another common type of community contribution includes integrations with popular frameworks or tools not directly supported by Buddy's official offerings, such as specific testing frameworks or cloud provider SDKs.

Although Buddy's official documentation primarily focuses on its own SDKs, resources like Google's guide to contributing to open source offer general advice for evaluating and contributing to community projects. Engaging with the Buddy community forums or GitHub repositories can also help discover and evaluate unofficial libraries. These community efforts extend the reach and utility of the Buddy platform, allowing developers to tailor their CI/CD solutions to specific needs and preferences that may not be covered by official tools alone. Always prioritize security when using third-party libraries, especially those that handle API keys or sensitive operational data.