Skip to main content
The ci.executeWorkflow action lets an Overcut workflow fire an external CI/CD workflow (starting with GitHub Actions support, more providers coming soon). You can kick-off builds, tests, deployments or any custom pipeline, either fire-and-forget or while waiting for completion and capturing the result.

​
Overview

When your automation needs to interact with an existing CI process (for example, to run an integration-test suite before continuing) you can add a ci.executeWorkflow step. The step calls the CI provider’s API, passes parameters and (optionally) pauses execution until the external workflow finishes.

Works with GitHub Actions

Provide repository, workflow file and ref; Overcut handles authentication.

Wait or Continue

Choose to block the workflow until success/failure, or continue immediately.

Dynamic Inputs

Pass trigger data or previous step outputs as inputs to the CI job.

Rich Status

Step status is Waiting for External while the CI job is running.

​
Parameters

​
Required Parameters

​
string
required
Repository owning the CI workflow, in owner/repo format.
​
string
required
File name (e.g., .github/workflows/test.yml) or numeric workflow ID of the job to run.

​
Optional Parameters

​
string
Git reference (branch, tag or SHA) to use when triggering the workflow.
Defaults to the repository’s default branch.
​
boolean
If true, the Overcut step waits until the external workflow completes and sets its final status accordingly. When enabled, the step enters Waiting for External state until completion.
​
object
Key/value map of input parameters defined by the target workflow. Supports string, number and boolean values.
If the target workflow defines a correlation_id input, pass a unique value (for example {{stepId}}) so Overcut can reliably identify the triggered run. See Identifying the Triggered Run.

​
Identifying the Triggered Run

GitHub’s workflow dispatch API does not return a run ID by default. After triggering, Overcut searches recent runs to find the one it just started so it can track its status. For guaranteed identification, declare a correlation_id input in your GitHub Actions workflow:
Then pass a unique value from the Overcut step. The {{stepId}} expression resolves to a unique identifier for the current step execution:
Overcut matches the triggered run by its correlation_id input and tracks exactly that run. The Correlation ID also appears in the step logs. If the target workflow does not define a correlation_id input, Overcut falls back to the most recent run triggered on the same branch by the connected account. This works for occasional triggers, but it can attach to the wrong run when the same workflow is triggered concurrently. Use correlation_id whenever concurrent triggers are possible.

​
Step Configuration

In the Workflow Builder:
  1. Add a new Action step and select Execute CI Workflow.
  2. Enter the repository and workflow file.
  3. (Optional) Specify ref, inputs and wait for completion.
  4. Connect subsequent steps. If you enabled wait for completion, downstream steps will run only after the CI job succeeds (or fails based on your on-failure policy).
Execute CI Workflow form

​
Example

The step triggers the specified GitHub Actions workflow on the PR’s commit and pauses execution. While the CI job runs, the step status shows Waiting for External. Once finished, Overcut records the result and continues the workflow.
Downstream steps see {{outputs.run-tests.status}} reflecting success, failure or cancelled (when waitForCompletion: true).

​
See Also