Does Codeship offer official SDKs for languages other than Ruby?

Codeship's primary official programmatic tool is the Ruby-based CLI. While there aren't official SDKs for other specific languages, the platform provides a well-documented RESTful API that enables developers to create custom clients or use community-contributed libraries in any language.

How do I authenticate with the Codeship API using an SDK or CLI?

Authentication with the Codeship API typically requires an API key. For the Codeship CLI, you can configure this key using `codeship configure` or by setting the `CODESHIP_API_KEY` environment variable. When interacting directly with the API, the key is usually passed in the `Authorization` header as a Bearer token.

Can I use Codeship SDKs to manage Codeship Pro projects?

Yes, the Codeship CLI and the underlying API support both Codeship Basic and Codeship Pro projects. You can list, trigger, and get the status of builds for projects configured with either service type.

Where can I find my Codeship API key?

Your Codeship API key can be generated and found within your Codeship account settings. Navigate to the 'API Access' section in your account dashboard to manage your API keys.

Are there any community-maintained SDKs for Codeship?

While Codeship does not officially endorse or maintain them, the open nature of its API encourages community development. You can often find community-maintained API wrappers or client libraries for languages like Python, Go, or Node.js by searching platforms like GitHub. Always verify the quality and maintenance status of community projects.

What kind of tasks can I automate with the Codeship CLI?

The Codeship CLI allows you to automate various tasks, including listing projects, triggering new builds for specific branches, retrieving detailed status information for builds, and potentially managing other project-related configurations programmatically. This enables integration into custom scripts and external tools.

Codeship SDKs & Libraries: Official & Community Integrations

Codeship SDKs & Libraries provide programmatic interfaces for interacting with Codeship's CI/CD platform. These tools, primarily CLIs and API clients, enable developers to automate build, test, and deployment processes, manage projects, and retrieve build status directly from their development environments or custom scripts. They support various languages and facilitate integration into existing workflows.

SDKs overview

Codeship, a continuous integration and delivery (CI/CD) platform, provides tools for developers to automate the testing and deployment of their applications. While the primary interaction with Codeship often occurs through its web interface or by configuring codeship-services.yml and codeship-steps.yml files for Codeship Pro projects, developers can also extend its functionality and integrate it into custom workflows using its API and associated SDKs and libraries.

The platform offers a robust RESTful API, allowing programmatic access to functionalities such as triggering builds, fetching build status, and managing projects. This API forms the foundation for both official tools and community-contributed libraries. The official tooling primarily focuses on a command-line interface (CLI) that simplifies common tasks.

Codeship supports various deployment targets and integrations, including cloud providers like AWS, Google Cloud, and Azure, as well as container registries and notification services. While dedicated SDKs for every integration point are not always provided directly by Codeship, the open nature of its API encourages the development of custom scripts and community-maintained wrappers.

For teams utilizing Docker, Codeship Pro offers granular control over the build environment, enabling developers to define custom services and steps using Docker Compose-like syntax. This approach minimizes the need for extensive SDKs to manage the build process itself, as much of the configuration is handled declaratively within the project's repository.

Official SDKs by language

Codeship primarily offers an official command-line interface (CLI) tool that interacts with its API. This CLI is developed in Ruby and is the main official programmatic interface provided by Codeship for automating tasks and integrating with the platform outside of the web UI. While not a full SDK in the traditional sense for every language, it provides a comprehensive set of commands for managing Codeship projects, builds, and deployments.

Official Codeship CLI

The Codeship CLI is a Ruby gem that allows users to interact with Codeship's API from their terminal. It supports various operations, including triggering builds, fetching build statuses, and managing project settings. It is particularly useful for scripting CI/CD workflows and integrating Codeship into custom tools.

Table of Official SDKs

Language	Package/Tool	Description	Maturity
Ruby	`codeship-cli`	Command-line interface for Codeship API interaction.	Stable, Actively Maintained

Installation

The primary official tool for Codeship is its Ruby-based CLI. Installation typically involves using RubyGems, Ruby's package manager. Before installation, ensure you have a compatible Ruby environment set up on your system (Ruby version 2.0.0 or higher is generally recommended for modern gem installations).

Prerequisites

Ruby (version 2.0.0+)
RubyGems

Installation Steps for Codeship CLI

Install Ruby and RubyGems: If you don't have Ruby installed, you can use a version manager like rbenv or rvm, or install it via your operating system's package manager. For example, on macOS with Homebrew, you might run brew install ruby.
Install the Codeship CLI gem: Open your terminal and execute the following command:
```
gem install codeship-cli
```
This command fetches the codeship-cli gem from RubyGems.org and installs it on your system. You might need to use sudo gem install codeship-cli depending on your Ruby environment configuration.
Verify installation: After installation, you can verify that the CLI is correctly installed and accessible by checking its version:
```
codeship --version
```
This should output the installed version of the Codeship CLI.
Configure API Key: To use the CLI, you need to configure your Codeship API key. This can typically be done by running codeship configure and following the prompts, or by setting the CODESHIP_API_KEY environment variable. Your API key can be generated from your Codeship account settings.

Quickstart example

This quickstart demonstrates how to use the Codeship CLI to list your projects and trigger a build for a specific project. This assumes you have already installed and configured the Codeship CLI with your API key.

Example: Listing Projects and Triggering a Build

First, ensure your API key is configured. If not, run codeship configure and enter your API key when prompted. You can find your API key in your Codeship account settings under "API Access" (Codeship API Overview).

Step 1: List all your Codeship projects

This command will fetch and display a list of all projects associated with your Codeship account, along with their respective UUIDs (Universally Unique Identifiers).

codeship projects

The output will resemble:

[
  {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "My-WebApp",
    "repository_name": "my-org/my-webapp",
    "type": "Pro"
  },
  {
    "uuid": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "name": "Another-Service",
    "repository_name": "my-org/another-service",
    "type": "Basic"
  }
]

Step 2: Trigger a new build for a specific project

Once you have the UUID of the project you want to build (e.g., from the codeship projects output), you can trigger a new build. Replace <PROJECT_UUID> with the actual UUID of your project and <BRANCH_NAME> with the branch you wish to build (e.g., main or develop).

codeship build <PROJECT_UUID> <BRANCH_NAME>

For example, to trigger a build on the main branch for the My-WebApp project:

codeship build xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx main

The command will return information about the newly triggered build, including its UUID and initial status.

Step 3: Get the status of a specific build

You can monitor the status of a build using its UUID. Replace <BUILD_UUID> with the UUID returned from the codeship build command.

codeship get build <BUILD_UUID>

This command provides detailed information about the build's current state, including its status (e.g., running, success, error), start and end times, and associated commit information.

Community libraries

While Codeship provides a strong official CLI, the underlying Codeship API is fully documented and accessible, encouraging community development of libraries and integrations. Developers often create custom scripts or API wrappers in various programming languages to fit specific needs that might not be covered by the official CLI or to integrate Codeship status and controls into other dashboards or tools.

Common patterns for community contributions include:

Python Wrappers: Python is frequently used for scripting and automation, and several developers have created Python libraries to interact with the Codeship API. These often simplify authentication and provide Pythonic methods for API endpoints.
Go Clients: For performance-critical or backend services, Go-based clients might be developed to interact with the Codeship API, often seen in custom monitoring or deployment orchestration tools.
JavaScript/Node.js Modules: For web-based dashboards or serverless functions, Node.js modules can be written to fetch build statuses or trigger deployments, integrating Codeship into broader development ecosystems.
Custom Webhooks and Integrations: Codeship supports outgoing webhooks for build status notifications. Community members often develop small services that consume these webhooks and integrate with other platforms like Slack, Microsoft Teams, or custom internal tools. For example, a developer might create a Cloudflare Worker to process Codeship webhook payloads and reformat them for a specific chat application, extending beyond Codeship's native integrations.

These community-driven efforts often leverage the official API documentation to ensure compatibility and functionality. When considering a community library, it is advisable to check its maintenance status, documentation, and community support, as these can vary significantly compared to official tools.

Developers interested in contributing or finding existing community projects can often search platforms like GitHub for repositories tagged with "codeship" and the desired programming language (e.g., "codeship python," "codeship go"). The Codeship documentation itself occasionally links to popular community examples or provides guidance on how to build custom API integrations.

Codeship SDKs & Libraries: Official & Community Integrations

SDKs overview

Official SDKs by language

Official Codeship CLI

Table of Official SDKs

Installation

Prerequisites

Installation Steps for Codeship CLI

Quickstart example

Example: Listing Projects and Triggering a Build

Step 1: List all your Codeship projects

Step 2: Trigger a new build for a specific project

Step 3: Get the status of a specific build

Community libraries

Frequently asked questions

Reviews

Discussion

Written by