Integrations and components

Semaphore

Learn how to use Semaphore with SuperPlane.

Run and react to your Semaphore workflows

Triggers

On Pipeline Done Listen to Semaphore pipeline done events

Actions

Get Pipeline Get a Semaphore pipeline by ID

Run Workflow Run Semaphore workflow

On Pipeline Done

Trigger key: semaphore.onPipelineDone

The On Pipeline Done trigger starts a workflow execution when a Semaphore pipeline completes.

Use Cases

Pipeline orchestration: Chain workflows together based on pipeline completion
Status monitoring: Monitor CI/CD pipeline results
Notification workflows: Send notifications when pipelines succeed or fail
Post-processing: Process artifacts or results after pipeline completion

Configuration

Project: Select the Semaphore project to monitor
Refs: Optional ref filters (for example refs/heads/main)
Results: Optional pipeline result filters (for example passed, failed)
Pipelines: Optional pipeline file filters (for example .semaphore/semaphore.yml, .semaphore/production/deploy.yml)

Event Data

Each pipeline done event includes:

pipeline: Pipeline information including ID, state and result
workflow: Workflow information including ID and URL
project: Project information
result: Pipeline result (passed, failed, stopped, etc.)
state: Pipeline state (done)

Webhook Setup

This trigger automatically sets up a Semaphore webhook when configured. The webhook is managed by SuperPlane and will be cleaned up when the trigger is removed.

Example Data

{
  "data": {
    "blocks": [
      {
        "jobs": [
          {
            "id": "00000-00000-00000-00000-00000",
            "index": 0,
            "name": "Report result to SuperPlane",
            "result": "passed",
            "status": "finished"
          }
        ],
        "name": "Block #1",
        "result": "passed",
        "result_reason": "test",
        "state": "done"
      }
    ],
    "organization": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "test"
    },
    "pipeline": {
      "created_at": "2026-01-19T12:00:00Z",
      "done_at": "2026-01-19T12:00:00Z",
      "error_description": "",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Initial Pipeline",
      "pending_at": "2026-01-19T12:00:00Z",
      "queuing_at": "2026-01-19T12:00:00Z",
      "result": "passed",
      "result_reason": "test",
      "running_at": "2026-01-19T12:00:00Z",
      "state": "done",
      "stopping_at": "1970-01-01T00:00:00Z",
      "working_directory": ".semaphore",
      "yaml_file_name": "semaphore.yml"
    },
    "project": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "test"
    },
    "repository": {
      "slug": "test/test",
      "url": "https://github.com/test/test"
    },
    "revision": {
      "branch": {
        "commit_range": "0000000000000000000000000000000000000000^...0000000000000000000000000000000000000000",
        "name": "test"
      },
      "commit_message": "Merge branch 'test' into test",
      "commit_sha": "0000000000000000000000000000000000000000",
      "pull_request": null,
      "reference": "refs/heads/test",
      "reference_type": "branch",
      "sender": {
        "avatar_url": "https://avatars2.githubusercontent.com/u/0000000000000000000000000000000000000000?s=460\u0026v=4",
        "email": "[email protected]",
        "login": "test"
      },
      "tag": null
    },
    "version": "1.0.0",
    "workflow": {
      "created_at": "2026-01-19T12:00:00Z",
      "id": "00000000-0000-0000-0000-000000000000",
      "initial_pipeline_id": "00000000-0000-0000-0000-000000000000"
    }
  },
  "timestamp": "2026-01-19T12:00:00Z",
  "type": "semaphore.pipeline.done"
}

Get Pipeline

Component key: semaphore.getPipeline

The Get Pipeline component fetches a Semaphore pipeline by its ID and returns its current state, result and metadata.

Use Cases

Pipeline status checking: After Run Workflow starts a pipeline, fetch its status to decide when to proceed
Pipeline lookup: Look up the result of a specific pipeline from event data to get full details
Conditional deployment: Build a status-check step that verifies a pipeline before triggering dependent actions

Configuration

Pipeline ID: The Semaphore pipeline ID (supports expressions, e.g. {{ event.pipeline.id }})

Output

Returns the pipeline object including:

Pipeline ID (ppl_id)
Pipeline name
Workflow ID (wf_id)
State (e.g. running, done)
Result (e.g. passed, failed)

Example Output

{
  "data": {
    "branch_name": "main",
    "commit_message": "feat: add new feature",
    "commit_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "created_at": "2026-01-22T15:32:47.000000Z",
    "done_at": "2026-01-22T15:32:56.000000Z",
    "error_description": "",
    "name": "Initial Pipeline",
    "ppl_id": "00000000-0000-0000-0000-000000000000",
    "project_id": "22222222-2222-2222-2222-222222222222",
    "promotion_of": "",
    "result": "passed",
    "result_reason": "test",
    "running_at": "2026-01-22T15:32:48.000000Z",
    "state": "done",
    "terminated_by": "",
    "wf_id": "11111111-1111-1111-1111-111111111111",
    "working_directory": ".semaphore",
    "yaml_file_name": "semaphore.yml"
  },
  "timestamp": "2026-01-22T15:32:56.061430218Z",
  "type": "semaphore.pipeline"
}

Run Workflow

Component key: semaphore.runWorkflow

The Run Workflow component triggers a Semaphore CI/CD workflow and waits for it to complete.

Use Cases

CI/CD orchestration: Trigger builds and deployments from SuperPlane workflows
Pipeline automation: Run Semaphore pipelines as part of workflow automation
Multi-stage deployments: Coordinate complex deployment pipelines
Workflow chaining: Chain multiple Semaphore workflows together

How It Works

Creates and starts a Semaphore workflow with the specified pipeline file and parameters
Waits for the pipeline to complete (monitored via webhook and polling)
Routes execution based on pipeline result:
- Passed channel: Pipeline completed successfully
- Failed channel: Pipeline failed or was cancelled

Configuration

Project: Select the Semaphore project containing the workflow
Pipeline File: Path to the pipeline YAML file (e.g., .semaphore/pipeline.yml)
Ref: Git reference to run the workflow on (branch, tag, pull request, or commit SHA)
Commit SHA: Optional specific commit SHA to run (if not provided, uses latest from ref)
Parameters: Optional workflow parameters as key-value pairs (supports expressions)
Add OIDC assertion: Send SUPERPLANE_OIDC_ASSERTION so CI can confirm this run was triggered by SuperPlane

Injected Parameters

SuperPlane automatically adds these workflow parameters when triggering Semaphore:

SUPERPLANE_EXECUTION_ID: The SuperPlane node execution ID
SUPERPLANE_CANVAS_ID: The SuperPlane canvas ID
SUPERPLANE_OIDC_ASSERTION: When Add OIDC assertion is enabled, a signed OIDC assertion attesting this workflow was triggered by SuperPlane

Verifying Triggers in CI

To verify that a Semaphore job was triggered by SuperPlane, verify SUPERPLANE_OIDC_ASSERTION before running any steps. Check every claim your policy depends on. For example:

superplane oidc verify \
  --audience semaphore \
  --claim org_id=eb3aca82-3864-4f76-b1d6-f670c297f136 \
  --claim app_id=c4d5e6f7-8901-4234-a567-890123456789 \
  --claim pipeline_file=.semaphore/production/deploy.yml \
  --claim node_id=deploy-production

The command reads the token from the environment, fetches JWKS from your SuperPlane instance and verifies the signature.

Output Channels

Passed: Emitted when pipeline completes successfully
Failed: Emitted when pipeline fails or is cancelled

Notes

The component automatically sets up webhook monitoring for pipeline completion
Falls back to polling if webhook doesn’t arrive
Can be cancelled, which will stop the running Semaphore workflow

Example Output

{
  "data": {
    "blocks": [
      {
        "jobs": [
          {
            "id": "00000-00000-00000-00000-00000",
            "index": 0,
            "name": "Job #1",
            "result": "passed",
            "status": "finished"
          }
        ],
        "name": "Block #1",
        "result": "passed",
        "result_reason": "test",
        "state": "done"
      }
    ],
    "organization": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "test"
    },
    "pipeline": {
      "created_at": "2026-01-22T15:32:47Z",
      "done_at": "2026-01-22T15:32:55Z",
      "error_description": "",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "Initial Pipeline",
      "pending_at": "2026-01-22T15:32:48Z",
      "queuing_at": "2026-01-22T15:32:48Z",
      "result": "passed",
      "result_reason": "test",
      "running_at": "2026-01-22T15:32:48Z",
      "state": "done",
      "stopping_at": "1970-01-01T00:00:00Z",
      "working_directory": ".semaphore",
      "yaml_file_name": "semaphore.yml"
    },
    "project": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "test"
    },
    "repository": {
      "slug": "test/test",
      "url": "https://github.com/test/test"
    },
    "revision": {
      "branch": {
        "commit_range": "0000000000000000000000000000000000000000^...0000000000000000000000000000000000000000",
        "name": "test"
      },
      "commit_message": "test",
      "commit_sha": "0000000000000000000000000000000000000000",
      "pull_request": null,
      "reference": "refs/heads/test",
      "reference_type": "branch",
      "sender": {
        "avatar_url": "https://example.com/avatar.png",
        "email": "[email protected]",
        "login": "test"
      },
      "tag": null
    },
    "version": "1.0.0",
    "workflow": {
      "created_at": "2026-01-22T15:32:47Z",
      "id": "00000000-0000-0000-0000-000000000000",
      "initial_pipeline_id": "00000000-0000-0000-0000-000000000000"
    }
  },
  "timestamp": "2026-01-22T15:32:56.061430218Z",
  "type": "semaphore.workflow.finished"
}