> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute CI Workflow Action

> Trigger external CI/CD pipelines, such as GitHub Actions, directly from your Overcut workflows using the `ci.executeWorkflow` action.

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.

<CardGroup cols={2}>
  <Card title="Works with GitHub Actions" icon="github">
    Provide repository, workflow file and ref; Overcut handles authentication.
  </Card>

  <Card title="Wait or Continue" icon="hourglass-half">
    Choose to block the workflow until success/failure, or continue immediately.
  </Card>

  <Card title="Dynamic Inputs" icon="sliders">
    Pass trigger data or previous step outputs as inputs to the CI job.
  </Card>

  <Card title="Rich Status" icon="bell">
    Step status is *Waiting for External* while the CI job is running.
  </Card>
</CardGroup>

***

## Parameters

### Required Parameters

<ParamField path="repoFullName" type="string" required>
  Repository owning the CI workflow, in `owner/repo` format.
</ParamField>

<ParamField path="workflowId" type="string" required>
  File name (e.g., `.github/workflows/test.yml`) **or** numeric workflow ID of the job to run.
</ParamField>

### Optional Parameters

<ParamField path="ref" type="string" required={false}>
  Git reference (branch, tag or SHA) to use when triggering the workflow.<br />
  Defaults to the repository's default branch.
</ParamField>

<ParamField path="waitForCompletion" type="boolean" required={false}>
  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.
</ParamField>

<ParamField path="inputs" type="object" required={false}>
  Key/value map of input parameters defined by the target workflow. Supports string, number and boolean values.
</ParamField>

***

## 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).

<img src="https://mintlify.s3.us-west-1.amazonaws.com/overcut/images/workflows/ci-execute-workflow/form.png" alt="Execute CI Workflow form" />

***

## Example

```yaml theme={null}
steps:
  - id: "run-tests"
    name: "Run Integration Tests"
    action: "ci.executeWorkflow"
    params:
      repoFullName: "acme/monolith"
      workflowId: ".github/workflows/integration.yml"
      ref: "{{trigger.pullRequest.headSha}}"
      waitForCompletion: true
      inputs:
        environment: "staging"
        runE2E: true
```

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.

***

## Related Status

| Status                   | When It Appears                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| **Waiting for External** | The step is waiting for an external system (e.g., CI workflow) to finish before proceeding. |

Downstream steps see `{{outputs.run-tests.status}}` reflecting `success`, `failure` or `cancelled` (when `waitForCompletion: true`).

***

## See Also

* [Triggers](/docs/workflows/triggers) – start workflows from PR events or slash commands
* [Git Clone](/docs/workflows/git-clone) – provide code to your CI workflows
* [Integrations: GitHub](/docs/integrations/github) – configuring repository access tokens