Step packs

What is a step pack?#

A step pack holds reusable steps your team defines once and can use in any pipeline. Each step runs in a container image. Pipelines call a step with uses::

steps:
  - name: Tell the team
    uses: slack/notify@1.2
    with:
      channel: "#releases"
      webhook_url: "{{.SLACK_URL}}"

Step packs are managed in the console under Delivery > Step packs.

Prerequisites#

• The developer or admin role. The viewer role can look at step packs but not change them.
• An environment with an agent, for test runs.

Create a pack#

1. On Delivery > Step packs, press New step pack.
2. Pick how to start:
   • Start from a template: ready-made, working examples such as a Slack message, a health check, Helm and tests.
   • Convert a SHELL step: a SHELL step from your step library that has an image and a command becomes the first step of a new pack draft. The original step stays as it is.
   • Blank, YAML or zip: start empty, paste a plugin.yaml followed by one step.yaml per step (separated by ---), or upload a zip downloaded with Export zip from another console.
3. Name the pack. The name uses lowercase letters, digits and dashes, and cannot change later.

Changes save automatically as a draft. Pipelines only see a version after you publish it.

Define a step#

A step can run in one of two ways:

• Script: a script runs in the base image you pick; no image build is needed. The script can be at most 64 KiB.
• Own image: bring an image that already contains your tool. Use Pin to digest to turn the tag into a digest; since a tag can move, you are asked to pin it before you publish.

Inputs#

In scripts, read inputs from the environment ("$INPUT_CHANNEL"). Do not write {{.INPUT_CHANNEL}} into a command: the value is placed into the script text before the shell parses it and could run as code. For secrets, prefer the $INPUT_<NAME>_FILE file.

Outputs#

A step writes its outputs to the $EJO_OUTPUT file as NAME=value lines. Only declared outputs reach later steps; system names such as WorkDir are refused. Inside the step, the repository is at /workspace.

Test a step#

Run test runs the draft of a step once in an environment you pick, before you publish. Test runs do not count in metrics, DORA, notifications or dashboards. In environments that are production or need approval, freeze windows and approvals apply to test runs too.

Publish a version#

Publish a version releases the draft as a new version. EJO suggests a version based on the changes:

A published version never changes.

Use it in a pipeline#

• The version can be written as 1, 1.2 or 1.2.0; it resolves to the matching published version.
• with: values may be {{.VAR}} templates. Secret inputs accept only a single variable reference.
• The reference is resolved when the pipeline version is created, and the image digest is stored in that version. Even if the pack changes later, the pipeline version keeps running the same image.
• A missing required input, a value that does not fit its type, or an unknown or withdrawn version stops the pipeline version from being created.

The Where it is used section on the pack page shows which pipelines call the pack's steps.

Withdraw a version#

You can pull back a faulty version with Withdraw; a reason is required. Only admins can withdraw.

• A withdrawn version cannot go into a new pipeline version.
• A run that still pins it fails when an agent claims it, with slack/notify@1.1.0 was withdrawn: <reason>.
• Pipelines that use it get a warning.

Step image policy#

Each environment has a Step image policy: Off, Warn or Enforce. It applies the signature and critical vulnerability rules to the images of pack steps and SHELL steps with an image. Warn runs the step and logs the violation; Enforce fails the step with the reason. See Supply chain security.

Note: Packs marked Server, read-only cannot be changed in the console. Use Copy to a new pack to create your own pack and change that.

Next steps#

• Pipeline definition
• Secrets and variables
• Supply chain security