Marketplace & custom steps

Marketplace & custom steps

FlightStack’s built-in 17 job types cover the Flutter happy path. For everything else — custom signing flows, internal tooling, weird deployment targets — the marketplace hosts versioned, declarative step specs you can drop into any pipeline.

The Step Contract (v2)

Every step is described by a YAML spec that follows the v2 step contract. The contract defines what the agent expects:

# Example spec — published as acme/notify-internal@1.0.0
apiVersion: flightstack/v2
kind: Step
metadata:
  ref: acme/notify-internal@1.0.0
  name: Notify internal incident channel
  description: Pushes a structured incident message to Acme's internal hub.
spec:
  inputs:
    - name: incidentId
      type: string
      required: true
    - name: severity
      type: string
      default: "info"
      enum: [info, warning, critical]
  outputs:
    - name: messageUrl
      description: Permalink to the posted message
  run:
    - shell: bash
      script: |
        curl -s -X POST https://hub.acme.internal/api/incidents \
          -d "id=$FS_IN_INCIDENT_ID" \
          -d "severity=$FS_IN_SEVERITY" \
          -o response.json
        fs-output messageUrl "$(jq -r .url response.json)"

The agent reads the spec, materializes FS_IN_* env vars from the declared inputs, runs the steps, and captures fs-output … calls as outputs.

Consuming a marketplace step

In a pipeline definition, reference the step by <publisher>/<name>@<version>:

jobs:
  - id: notify
    uses: acme/notify-internal@1.0.0
    inputs:
      incidentId: "${{ context.runId }}"
      severity: critical

The visual editor’s job palette includes every step the org has access to (built-in, internally published, and marketplace).

Resolution

The server resolves uses: references against the marketplace registry on every run. Offline (CLI) linting can’t resolve unknown refs — those surface as warnings unless you pass --strict. See flightstack pipeline lint.

Pinning versions

@1.0.0 pins exactly. @^1.0.0 (caret) allows compatible minor/patch upgrades. @latest always grabs the newest published version — convenient for internal steps you control, risky for third-party ones. Default to exact pins for production pipelines.

Publishing a custom step

1. Author the spec as a flightstack.yml file in a Git repo (one repo per step or one repo for many — both are supported).
2. Run flightstack pipeline lint flightstack.yml to catch structural issues.
3. Use flightstack publisher to register your publisher profile (once per org).
4. Use flightstack template (or the dashboard’s Marketplace → Publish flow) to push a new version of the step.

Published steps live in your organization’s namespace and are private by default. Make a step public by toggling its visibility in the marketplace UI.

Visibility levels

Level	Who can see
Private	Only your org.
Org-shared	Other orgs you explicitly grant access to.
Public	Listed in the public marketplace; usable by every account.

Internal vs marketplace

For one-off automation, a shell job is faster to author than a step spec. Reach for a custom step when:

• The same logic is used across multiple pipelines.
• You want input validation and typed outputs.
• You want version pinning + a changelog.
• You want non-engineers to be able to drag it into a canvas.

See also

• Shell job — the lightest-weight alternative
• Variables → step outputs — fs-output + FS_IN_*
• flightstack pipeline lint — validate specs locally