Creating Steps

If you cannot find a step that solves a challenge you are facing in the Steps Store, you can create your own step and publish it. Steps are similar to any other projects on Wercker, but instead of deploying to a cloud provider, you deploy to the Steps Store in order to make the step available.

To be able to publish a step, you first need a Wercker application containing the following files:

  • wercker.yml file with a internal/publish-step step
  • run.sh file which is the entry-point of your step
  • step manifest file called step.yml

Although a step can technically be written in any language, we recommended writing them in bash or in golang. The former is usually installed on most Docker containers, whereas the latter compiles to a single binary. Both programming languages do not require any dependencies or libraries to be present that might not be installed in various Docker containers people use, making them quite portable. If you do create a step in a different programming language, and require certain run time components, make sure to document this in the step README.

The Step Manifest file

The step manifest file defines the configuration of your step. Below an example of a Wercker step manifest which we’ll go over:

# step.yml
name: slack-notifier
version: 1.4.0
summary: Posts Wercker build/deploy status to a Slack channel.
tags:
 - notification
 - webhook
 - slack
properties:
- name: url
 type: string
 required: true
- name: channel
 type: string
 required: false
- name: username
 type: string
 required: false
- name: notify_on
 type: string
 required: false
- name: icon_url
 type: string
 required: false
- name: branch
 type: string
 required: false

The summary field is the description for the step. We recommend using a small single line or single paragraph description. All other documentation should be in the README.

Only name, version, and summary are required. All the following properties are optional, though we encourage people to use them.

The tags fields contains an array of strings with keywords of this step. We recommend a few tags (at most 5) to describe the step.

The keywords fields contains an array of strings with keywords of this step. We recommend a few tags (at most 5) to describe the step.

The properties field contains metadata describing the parameters that are available for the step. This is a map; the key is the name of the step, and the value is a object with the following properties:

  • name - the name of the property
  • type - the type of the data of the parameter. Currently supported: string.
  • required - boolean indicating if the parameter is required or not (currently not enforced).
  • default - value that gets used, if no parameter was provided through the wercker.yml

The run.sh file

The run.sh file contains the entrypoint your step logic. This should be bash code in the run.sh file itself. If you want to create a more complex application in a different language, than call this from within the run.sh file.

For each property you specified in your step.yml, Wercker sets a corresponding environment variable. For example, the value of the url property would be made available in the $WERCKER_SLACK_NOTIFIER_URL environment variable. The name of the environment variable will be WERCKER_ followed by the name of the step (from the step.yml) converted to uppercase and with hyphens changed to underscores, followed by another underscore and then the name of the property converted to uppercase.

Notice that any hyphens you use in your parameter names will be transformed to underscores.

The Publish-Step Step

In order to publish a step to the Steps Store, the step’s wercker.yml file needs to contain the publish-step step, usually at the end. Below is an example of the wercker.yml file for the aforementioned slack-notifier step:

# wercker.yml
box: debian:stable-slim
build:
 steps:
 - shellcheck:
 files: run.sh

 - script:
 name: prepare output
 code: rm -rf $WERCKER_ROOT/.git

publish:
 steps:
 - install-packages:
 packages: ca-certificates

 - internal/publish-step:
 owner: wercker

The publish-step step has the following optional parameters:

  • auth_token: contains the publishing user’s personal token
  • owner: can be used to specify the owner of the step (for example, an organization). NOTE: Be sure to change the owner to your user id or the organization you want to own the step.
  • private: used to publish private steps which are only accessible by the owner or all members in an organization, if the private step is owned by an organization

Having a separate pipeline publish (or deploy) which contains the publish-step step is not required.

Publishing your step

Publishing steps is done by deploying your step to the Steps Store. To do so create a project on Wercker for your step by going to Create and selecting Application.

Create Step

The build process will run in the same way as any other application on Wercker. After the application has built, and the build pipeline has run, you can then publish the step by selecting publish (or whichever pipeline you decided to contain the publish-step) from the Actions drop-down of any completed (green) build.

Publish Step

To see the completed step go to https://app.wercker.com/steps.

To use your step in another application, refer to it using the owner and step name, for example:

box: Debian
build:
 steps:
  # use the slack notifier step described above
  - owner/slack-notifier:
  URL: https://someplace.slack.com
  channel: my-channel

The owner should be replaced with the user or organization that owns this step. If you want to use a step owned by Wercker, you can omit the owner and just use the step name, slack-notifier.

If you want to use a specific version of a step, as opposed to just using the latest available version, then you can append the version after the step name, like this:

box: Debian
build:
   steps:
   # use the slack notifier step described above
   - owner/slack-notifier@1.1.0:
   URL: https://someplace.slack.com
   channel: my-channel

You can now publish private steps which are only accessible by the owner or all members in an organization, if the private step is owned by an organization.

You can publish a private step in one of the following two ways: - Use the --private parameter in the Wercker CLI. For example: wercker step publish --private, or - Add the private: true parameter to the publish-step step in the Wercker YAML file as follows:

publish:
  steps:
    - internal/publish-step:
        private: true

Note: You can only publish the new steps that you create to be private. You cannot publish the existing steps as private.