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

# CI Pipeline Tools

> Start GitLab pipelines and GitHub Actions workflows, follow their status, inspect failed job logs, cancel runs, and retry them.

## **Overview**

<Note>
  Save the credentials in a GitHub or GitLab connection before using these tools. The
  optional `connection` parameter accepts a saved connection such as
  `github.personal` or `gitlab.work`; omit it to use the platform's default connection.
  Repository access is checked for the current user or agent.
</Note>

### **Tool Name**

```json theme={null}
ci_pipeline_tools
```

### **Purpose**

The **ci\_pipeline\_tools** group gives agents one vocabulary for GitHub Actions and
GitLab CI: start a run, find and follow it, inspect the job that failed, cancel a run,
or retry it. GitHub runs are workflow runs; GitLab runs are pipelines.

## **Functions Available**

### **`ci_run_pipeline`**

Starts a GitHub Actions workflow or a GitLab pipeline on a branch or tag.

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`platform`** | String | none | Required. `github` or `gitlab`. |
| **`repository`** | String | none | Required. GitHub owner/name, or the full GitLab project path, including nested groups when applicable. |
| **`ref`** | String | none | Required branch or tag, such as `main` or `release/1.2`. |
| **`workflow`** | String | `None` | GitHub only. Required on GitHub; workflow file name such as `deploy.yml` or a numeric workflow id. Leave out for GitLab, which runs the project's `.gitlab-ci.yml`. |
| **`inputs`** | Object | `None` | Optional name/value pairs. GitHub passes them as declared workflow inputs; GitLab passes them as CI variables. Keys and values are converted to strings, and `None` becomes an empty string. |
| **`connection`** | String | platform default | Optional saved connection containing the credentials. |

```python theme={null}
ci_run_pipeline(
    platform="github",
    repository="acme/webapp",
    ref="main",
    workflow="deploy.yml",
    inputs={"environment": "staging"},
)
```

GitHub may accept the dispatch before it creates a run. In that case the result has
`dispatched=true` and `run_id=None`; use `ci_list_pipeline_runs` with the workflow to
find the newly created run instead of guessing an id.

### **`ci_get_pipeline_run`**

Checks one run and returns its status, ref, commit SHA, URL, and jobs. Pass the GitHub
Actions run ID or GitLab pipeline ID as `run_id`.

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`platform`** | String | none | Required. `github` or `gitlab`. |
| **`repository`** | String | none | Required repository identifier. |
| **`run_id`** | Integer | none | Required GitHub Actions run ID or GitLab pipeline ID. |
| **`connection`** | String | platform default | Optional saved connection containing the credentials. |

Poll this tool while a run is queued or running. Jobs can be empty until execution
starts. When a job fails, use `ci_get_pipeline_logs` to read its output.

### **`ci_list_pipeline_runs`**

Lists recent runs newest first. Use it to find a GitHub run after dispatch, inspect a
branch's recent CI history, or find a run ID to follow.

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`platform`** | String | none | Required. `github` or `gitlab`. |
| **`repository`** | String | none | Required repository identifier. |
| **`ref`** | String | `None` | Optional branch or tag filter. Omit to include all refs. |
| **`workflow`** | String | `None` | GitHub only. Optional workflow file name or numeric id. Omit to include every workflow. |
| **`limit`** | Integer | `20` | Optional number of runs to return. Values are bounded to `1` through `100`. |
| **`connection`** | String | platform default | Optional saved connection containing the credentials. |

### **`ci_get_pipeline_logs`**

Reads the failed job's log, falling back to the last job when no job has failed. The
end of the log is returned because failures usually appear there.

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`platform`** | String | none | Required. `github` or `gitlab`. |
| **`repository`** | String | none | Required repository identifier. |
| **`run_id`** | Integer | none | Required GitHub Actions run ID or GitLab pipeline ID. |
| **`max_log_bytes`** | Integer | `20000` | Optional maximum log size. Values are bounded to `1` through `200000`; the returned text is the tail of the log. |
| **`connection`** | String | platform default | Optional saved connection containing the credentials. |

The result includes `truncated=true` when the log exceeded the requested size. If the
run has no jobs yet, poll `ci_get_pipeline_run` and request the log again.

On GitHub the result also lists `failed_steps`, the steps of the job that did not
succeed. GitHub serves Actions logs from Azure Blob Storage, not from `api.github.com`,
so a deployment whose network egress does not reach that host cannot read the log. This
is the default on Snowflake. In that case the result has `success=false` but still
carries `failed_steps` and `annotations`: the `::error` and `::warning` lines the job
emitted, with file and line, read from the GitHub API. If the annotations cannot be
read, `annotations_error` says why. A GitHub App installation or fine-grained token
needs **Checks: read** for them. See
[GitHub Repository Integration](/docs/Setup/Setup-Github-EAI#github-actions-logs-on-snowflake)
to allow the log host.

### **`ci_cancel_pipeline_run`**

Requests cancellation of a run that is still executing.

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`platform`** | String | none | Required. `github` or `gitlab`. |
| **`repository`** | String | none | Required repository identifier. |
| **`run_id`** | Integer | none | Required GitHub Actions run ID or GitLab pipeline ID. |
| **`connection`** | String | platform default | Optional saved connection containing the credentials. |

Cancellation is asynchronous. Read the run again with `ci_get_pipeline_run` to see
the final state; do not submit the cancellation repeatedly.

### **`ci_retry_pipeline_run`**

Retries a completed run without requiring a new commit. GitHub reruns the workflow;
GitLab retries the failed jobs in the pipeline.

| **Name** | **Type** | **Default** | **Definition** |
| - | - | - | - |
| **`platform`** | String | none | Required. `github` or `gitlab`. |
| **`repository`** | String | none | Required repository identifier. |
| **`run_id`** | Integer | none | Required GitHub Actions run ID or GitLab pipeline ID. |
| **`connection`** | String | platform default | Optional saved connection containing the credentials. |

Follow the restarted run with `ci_get_pipeline_run`. Retrying consumes CI build
minutes and can repeat a deployment.

## **Typical Workflow**

1. Save and authorize the GitHub or GitLab connection.
2. Call `ci_run_pipeline` with the repository, ref, and (for GitHub) workflow.
3. If GitHub returns no `run_id`, call `ci_list_pipeline_runs` for that workflow.
4. Poll `ci_get_pipeline_run` until the run finishes.
5. If it fails, call `ci_get_pipeline_logs` to inspect the failed job.
6. Use `ci_cancel_pipeline_run` or `ci_retry_pipeline_run` only when the user confirms the action.

<Warning>
  These tools start real CI and can deploy. Confirm the target branch or tag before
  starting, cancelling, or retrying a run.
</Warning>