Resources are the basic building blocks of your pipelines. They typically contain information needed for jobs to execute and sometimes they also are used to store information produced by a job.
A key characteristic of resources is that they can be versioned. A specific version of a resource is immutable, i.e. it returns the same result every single time it is fetched.
They are predominantly used for the following reasons:
- Provide 3rd party secrets to the job runtime so that environment is configured with the right level of access rights to connect to external services. E.g., integration or cliConfig resources can be used to provide credentials safely.
- Supply information to set the context for the jobs to execute. E.g., params resources commonly store environment variables and version resources keep track of changing versions.
- A trigger to changes to the repo on the source control system. E.g., a gitRepo, ciRepo, or syncRepo can trigger jobs whenever the source code is updated.
- A trigger to execute a job. E.g., a time resource will trigger a job at set times.
- Act as an entity to store stateful information produced during the execution of a job. E.g., state resources are commonly used to share information between jobs. A job will also often update an image resource with a new tag.
Resources are defined in
shippable.yml as shown below:
resources: - name: <string> type: <resource type name> integration: <string> pointer: <object> seed: <object> version: <object>
For an explanation of each field, read the resources section of the anatomy of shippable.yml page.
A resource consists of the following components:
resourceIDwhich uniquely identifies the resource. This is unique across the entire platform and is auto-generated when a resource is added.
versionNumberwhich is created every time the resource is updated, resulting in a new versionNumber
versionNamewhich is an optional user-defined name.
metawhich is a json object containing the resource definition and information. For example, if you have a cluster resource, the pointer information is stored in this json object.
statewhich stores user-defined key-value pairs, if any, for the resource. For the
stateresource, this can also contain files in addition to key-value pairs
pathwhich stores data that was pulled by the resource. For example, for a
gitReporesource, this contains a clone of the Git repository.
To understand how you can access the above components through your job scripts, read our tutorial on Accessing resource data
All resources are versioned. A new resource version is created in two ways:
- When you update the resource definition in
- When a job updates an
This is critical if you want to be able to roll back, upgrade, or pin the resource to a particular point of time.
These are the types of resources that Shippable Workflow supports:
|ciRepo||Represents a CI project for a git repo|
|cliConfig||Configuration information for command-line tools|
|cluster||Cluster defines a collection of servers|
|dockerOptions||Configuration information for a container|
|file||Location of a file|
|gitRepo||Represents a source code repo|
|image||Represents a package on a registry|
|integration||Encrypted connection information to 3rd party services|
|loadBalancer||Represents load-balancer resources offered by cloud providers|
|notification||Resource to send alerts from the workflow|
|params||Environment variables used to prime your job runtime|
|replicas||Number of copies of the service to run|
|syncRepo||Used to define DevOps Assembly Lines|
|time||Trigger a job at a specific day and time|
If you need a resource that is not listed above, send us an email at email@example.com.