Stagefy

한국어

Contributions are welcome — see the Contributing guide.

Stagefy lets you define pipeline stages in YAML and reuse them across pipelines. It adds a global stagefy variable that you call from a Jenkinsfile, so stage definitions live in plain YAML files and are shared through use, template and iterated directives.

Because the stage logic ships inside the plugin, Jenkinsfiles only call stagefy.run(...); no custom shared-library code needs Script Security approval.

pipeline-as-yaml defines a whole pipeline in YAML. Stagefy does not replace it, it complements it: Stagefy focuses on reusing YAML at the stage level (use, template, iterated).

// Jenkinsfile
pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    stagefy.run('Jenkins.yml', 'build')
                }
            }
        }
    }
}

# Jenkins.yml
build:
  steps:
    - sh: "make build"
    - sh: "make test"

stagefy.run(file, stage) reads the YAML file from the workspace and runs the named stage inside a stage(...) block. In declarative pipelines the equivalent stagefy file: 'Jenkins.yml', stage: 'build' works directly in steps {} without a script {} block.

A stage is a top-level key in the YAML file. Its kind is decided by one of these keys:

when (Groovy expression, the stage is skipped when false) is accepted on every stage kind. Optional keys on a steps stage only: env (map of environment variables) and node (label to run on).

Security: script, evaluate and when run arbitrary Groovy outside the Script Security sandbox. Only load YAML files and scripts from sources you trust.

Template arguments ({name}) are inlined as text into sh steps, just like ${...} interpolation in a Jenkinsfile. When a value comes from outside (branch names, build parameters, over: env.VAR), quote it in the step (sh: "deploy.sh '{name}'") and make sure it cannot contain quotes or shell syntax. ${env.VAR} is different: it is passed as a shell variable and is never interpreted as code.

all:
  stages:
    - build
    - test from common.yml        # stage from another file
    - template: notify            # template used as a stage
      channel: ci

Use parallels: instead of stages: to run the entries in parallel. Stage names must be unique within one block, and circular references are rejected.

deploy:
  template:
    arguments: [target]
  steps:
    - sh: "./deploy.sh {target}"

release:
  stages:
    - iterated:
        template: deploy
        over: [dev, staging]      # or: env.TARGETS  (comma-separated)

Arguments are referenced as {name} inside template steps. over may be a list of scalars, a list of maps (each key becomes an argument; an optional _name key names the generated stage) or env.VAR_NAME holding a comma-separated list. Each item produces a stage named <template>_<item>. Templates may only contain steps; they cannot contain template or iterated themselves.

A JSON Schema for the stage YAML is provided at schema/stagefy.schema.json (draft-07). It gives completion and flags unknown keys in editors that use the YAML language server.

Reference it with a modeline at the top of a stage file:

# yaml-language-server: $schema=https://raw.githubusercontent.com/jenkinsci/stagefy-plugin/main/schema/stagefy.schema.json
build:
  steps:
    - sh: "make build"

or map it in VS Code settings.json (Red Hat YAML extension):

"yaml.schemas": {
  "./schema/stagefy.schema.json": ["Jenkins.yml", "stages/*.yml"]
}

The schema checks structure only; Groovy in when, evaluate and script and cross-file references are not validated.

Each YAML file is parsed once per build and cached. Files generated during the build are read on first use, but do not modify a file after it has been read: the change is not picked up.

mvn clean verify          # build, run tests and static analysis
mvn hpi:run               # start a development Jenkins with the plugin

The built plugin is target/stagefy.hpi.

• Installation guide
• Deployment guide
• Editor validation (JSON Schema)
• Contributing guide
• Changelog

Issues and pull requests are welcome. See CONTRIBUTING.md and record notable changes in CHANGELOG.md.

Licensed under the MIT License.