Anatomy of shippable.resources.yml

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.

Resources are defined in a yml-based configuration file shippable.resources.yml that is committed to source control in your Sync repository.

The anatomy of the resources configuration in shippable.resources.yml generally follows the structure below

  - name:           <string>
    type:           <resource type name>
    integration:    <string>                
    pointer:        <object>
    seed:           <object>
    version:        <object>
  • name -- an alphanumeric string (underscores are permitted) that makes it easy to infer what the resource represent e.g. aws_creds to represent AWS keys. This name is used to define the IN or OUT entities to Jobs.

  • type -- Name of the resource type that this resource is an instance of. Here is a list of all types

  • integration -- this may be required depending on the resource type. Integrations are an abstraction to 3rd party authentication secrets For e.g. webhook token, Docker hub credentials and so on

  • pointer -- section is used when the resource needs to reference something, usually on a third-party provider. For example, a cluster resource has a pointer section which needs cluster name, region name, etc. In case of gitRepo, pointer contains sourceName that points to the repo name along with other pieces of information like branch etc.

  • seed -- section is used to specify a starting value for a resource. This is relevant for resources like image since this tells Shippable what value to use for this resource when running the connected job for the first time. After the first run, the seed values are ignored. However, you can still use seed to reset the resource to start with a new value by changing it and committing the yml. This will create a new resource version as a new starting point.

  • version -- section contains information is not expected to change dynamically during a job run. For example, dockerOptions and params have several tags under the version section. Any time information changes in this section, a new version of the resource is created.

Further Reading