Integrating A Tool Or Service With CodeShip
If you want to use a third-party tool or service with CodeShip that we do not currently have examples or documentation set up for, it is usually fairly easy to get an integration working once you understand the necessary concepts for using external services.
If the service or tool you are integrating requires something like an API key or authentication token to be set as an environment variable, you will do this via a project’s encrypted environment variables that are encrypted and included in the codeship-services.yml file.
|Environment variables are loaded at run time, so they are only available after your services have built and become available. If you have a token (such as an SSH key) that instead needs to be available at build time for use inside the project’s Dockerfile, you will instead need to use encrypted build arguments which are available at build time.|
The CloudBees CodeShip Pro build environment is defined in a project’s codeship-services.yml file. This file uses Docker images, or Dockerfiles included in the repository, to build the containers that run all the commands in the CI/CD pipeline that are specified in the other required file - codeship-steps.yml.
Due to the fact that the containers built from the service definitions in the codeship-services.yml file execute all of the commands in the pipeline, any packages or environment-specific setup must be defined via this file as well as the project’s Dockerfiles.
As one example of this, if you have a CLI tool that is required to execute the tool’s commands, you will need the CLI to be installed via the project’s Dockerfile so that when the codeship-steps.yml passes the necessary command to that service the container has the tooling it needs to execute the command.
All commands on CloudBees CodeShip Pro are executed via the project’s codeship-steps.yml file. If the tool or service you are integrating has commands that must be directly called, you can do that as a new step, such as:
- name: your_service service: service_name command: service command here
You can also place these types of commands as scripts that you include in the repository instead, if you need to chain multiple commands together in a single step. For example:
- name: your_service service: service_name command: command.sh
As covered above, all of the steps take place inside the containers
you define in the
service portion of the step. So, as long as that
container is capable of executing the script or command you are passing
it, it will execute without issue.
The step itself is complete when an exit code is surfaced to CodeShip.
An exit code
0 means the step is successful, whereas any other exit
code means the step has failed and the build will be stopped.
If the service or tool you are integrating requires something like an API key or authentication token to be set as an environment variable, you will do this via a project’s environment variables.
You can do this by navigating to Project Settings and then clicking on the Environment tab.
CloudBees CodeShip Basic builds run on shared virtual machines with tooling
preinstalled. A user can install any package that they need via the
setup commands, including anything that requires
sudo or root access.
All commands on CloudBees CodeShip Basic are executed via the project’s setup and test commands. Setup commands happen before any tests are run, while test commands happen only after setup is complete.
Note that you should consider that tests can run in parallel when determine if a command should be a setup command or a test command, as well as whether it should execute only in one potential test pipeline or if it should execute in multiple test pipelines.