> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/codefresh.md).

# Codefresh

Pull Codefresh pipeline runs, builds, and audit logs into Google Sheets or BigQuery for CI/CD analytics and compliance tracking via Coupler.io.

Codefresh is a CI/CD platform built for Kubernetes and container-based workflows. It helps engineering teams build, test, and deploy software with pipelines, Helm charts, and runtime agents. Connecting Codefresh to Coupler.io lets you pull your pipeline runs, build records, audit logs, and analytics into any destination for reporting and analysis.

**Why connect Codefresh to Coupler.io?**

* Track build success rates, failure trends, and pipeline performance over time
* Centralize audit logs alongside data from other tools for compliance reporting
* Send CI/CD metrics to Google Sheets, BigQuery, or AI tools like ChatGPT or Gemini for deeper analysis
* Combine Codefresh data with project management sources using Join or Append transformations

## Prerequisites

* A Codefresh account with access to the data you want to export
* A Codefresh API key (generated from your Codefresh user settings)

## Quick start

{% hint style="success" %}
Start with the **Builds** entity — it's the most actionable dataset for tracking pipeline health and catching failure patterns early.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** From your Coupler.io dashboard, click **Add data flow** and search for **Codefresh** as your source.
{% endstep %}

{% step %}
**Enter your Codefresh API key.** In Codefresh, go to **User Settings → API Keys** and generate a new key. Copy it and paste it into the API key field in Coupler.io.
{% endstep %}

{% step %}
**Select the entity you want to import.** Choose from Builds, Pipelines, Audit logs, Analytics reports, or any of the other available entities. You can add more sources to the same data flow later.
{% endstep %}

{% step %}
**Set your start date and report parameters.** Use the date picker to set the earliest date for your data export. If you're pulling Analytics reports, also set the report granularity (daily, weekly, or monthly) and the report date range.
{% endstep %}

{% step %}
**Choose a destination.** Select where your data should land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude, ChatGPT, or Gemini.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute a manual sync and confirm data is arriving correctly.
{% endstep %}
{% endstepper %}

## Codefresh data overview

Codefresh exposes data across your entire CI/CD operation — from pipeline definitions and build records to audit trails, runtime agents, and Helm repositories. Here's a breakdown of what each entity contains and how you can use it.

## Entities at a glance

| Entity             | Best used for                                                |
| ------------------ | ------------------------------------------------------------ |
| Builds             | Pipeline run history, success/failure rates, duration trends |
| Pipelines          | Pipeline definitions, triggers, and configuration            |
| Audits             | Compliance tracking, user activity monitoring                |
| Analytics reports  | Aggregated CI/CD metrics over time                           |
| Analytics metadata | Understanding report structure and available dimensions      |
| Projects           | Organizing and filtering pipelines by project                |
| Agents             | Monitoring runtime infrastructure                            |
| Contexts           | Reviewing shared variables and secrets metadata              |
| Execution contexts | Debugging runtime environments                               |
| Accounts           | User management and account inventory                        |
| Account settings   | Configuration auditing                                       |
| Step types         | Cataloging custom pipeline steps                             |
| Helm repos         | Helm chart repository inventory                              |

## Builds

#### Key fields

| Field         | Description                                  |
| ------------- | -------------------------------------------- |
| Build ID      | Unique identifier for the build run          |
| Pipeline name | The pipeline that triggered the build        |
| Status        | Outcome: success, failure, error, terminated |
| Started at    | Timestamp when the build began               |
| Finished at   | Timestamp when the build completed           |
| Duration      | Total execution time                         |
| Triggered by  | User or event that triggered the build       |
| Branch        | Git branch associated with the build         |
| Commit SHA    | Git commit hash                              |
| Error message | Failure reason if the build did not succeed  |

## Pipelines

#### Key fields

| Field       | Description                               |
| ----------- | ----------------------------------------- |
| Pipeline ID | Unique identifier                         |
| Name        | Pipeline display name                     |
| Project     | Associated project                        |
| Created at  | Pipeline creation date                    |
| Updated at  | Last modification date                    |
| Triggers    | Events configured to trigger the pipeline |
| Steps       | Step definitions in the pipeline          |

## Audits

#### Key fields

| Field       | Description                                           |
| ----------- | ----------------------------------------------------- |
| Event type  | Action performed (e.g., pipeline updated, user added) |
| User        | Who performed the action                              |
| Timestamp   | When the event occurred                               |
| Entity type | What was affected (pipeline, account, context, etc.)  |
| Entity ID   | Identifier of the affected resource                   |
| IP address  | Origin IP of the action                               |

## Analytics reports

#### Key fields

| Field              | Description                           |
| ------------------ | ------------------------------------- |
| Report period      | Date range covered by the report      |
| Granularity        | Daily, weekly, or monthly aggregation |
| Total builds       | Count of builds in the period         |
| Success rate       | Percentage of successful builds       |
| Average duration   | Mean build execution time             |
| Pipeline breakdown | Per-pipeline performance metrics      |

## Common metric combinations

* **Builds + Pipelines** — Join on pipeline ID to enrich build records with pipeline metadata for full-context reporting
* **Builds over time** — Use Aggregate transformation to calculate daily or weekly success rates from raw build records
* **Audits + Accounts** — Join on user ID to map audit events to named users for compliance reports
* **Analytics reports (Append)** — Append reports from multiple date ranges to build a continuous historical dataset

## Use cases by role

{% tabs %}
{% tab title="Engineering leads" %}

* Monitor build success and failure rates across all pipelines to identify flaky tests or unstable stages
* Track average build duration over time to catch performance regressions before they slow down the team
* Compare pipeline activity across projects to balance workload and infrastructure costs
  {% endtab %}

{% tab title="DevOps / Platform teams" %}

* Audit agent activity and execution contexts to ensure runtime infrastructure is healthy
* Review Helm repo configurations and context settings to maintain consistent environments
* Export audit logs to BigQuery or a SIEM tool for compliance and incident investigation
  {% endtab %}

{% tab title="Engineering managers" %}

* Use Analytics reports in Google Sheets or Looker Studio to report on deployment frequency and change failure rate
* Feed build data into ChatGPT or Gemini to generate narrative summaries of team delivery health
* Track pipeline trends by project to identify teams that may need additional tooling support
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* Build history depth depends on your Codefresh plan — enterprise accounts retain longer build history
* Analytics reports require setting both granularity and date range parameters; missing either may result in empty data
* The Audits entity only captures events within your account's retention window as configured in Codefresh
* Contexts contain metadata about shared variables but do not expose secret values
* Agent data reflects the current state of registered agents and is not historical

## Codefresh common issues

### Connection issues

<details>

<summary>API key is rejected or returns an authentication error</summary>

Double-check that you copied the full API key from Codefresh — truncated keys are a common cause of auth failures. In Codefresh, go to **User Settings → API Keys** and regenerate a new key if you're unsure. Make sure the key has not been revoked or expired. Paste it fresh into the Coupler.io source settings without any leading or trailing spaces.

</details>

<details>

<summary>Connection succeeds but returns no data</summary>

Check your **start date** setting. If the start date is set too far in the future or beyond your account's data retention window, the sync will return empty results. Use the date picker to set a start date within the range where you know builds or events exist.

</details>

### Missing data

<details>

<summary>Analytics reports entity returns empty results</summary>

Analytics reports require both **report granularity** and **report date range** to be set. If either is missing or the date range doesn't match any completed reporting periods, the entity will return no rows. Make sure your date range covers at least one full granularity period (e.g., a full day for daily granularity).

</details>

<details>

<summary>Builds from a specific pipeline are missing</summary>

Codefresh build history is scoped to your account. If a pipeline was deleted, its build records may no longer be accessible via the API. Also confirm that the API key belongs to an account that has access to that pipeline — builds from sub-accounts or teams you're not a member of won't appear.

</details>

<details>

<summary>Audit logs don't go back far enough</summary>

Audit log retention is controlled by your Codefresh plan and account settings. Coupler.io can only retrieve what Codefresh exposes via its API — if events older than a certain date aren't returned, they've likely been purged from Codefresh's retention window.

</details>

### Permission errors

<details>

<summary>Certain entities return a 403 or permission denied error</summary>

Some Codefresh entities (like Accounts or Account settings) require admin-level access. If your API key is tied to a non-admin user, you'll get permission errors on those entities. Generate an API key from an admin account, or limit your data flow to entities your current user has access to.

</details>

### Data discrepancies

<details>

<summary>Build counts in Coupler.io don't match what I see in the Codefresh UI</summary>

The Codefresh UI may apply default filters (e.g., showing only the last 30 days, or filtering by a specific pipeline). Your Coupler.io data flow pulls based on the start date you configured with no additional filters applied by default. Adjust your start date or filter the exported data in your destination to match the UI view you're comparing against.

</details>

<details>

<summary>Analytics report metrics differ from in-app analytics</summary>

The in-app analytics dashboard may use a different aggregation method or exclude certain build types (e.g., cancelled builds). Check that your report granularity and date range in Coupler.io exactly match the period shown in the Codefresh analytics UI.

</details>

### Rate limits

<details>

<summary>Sync fails or slows down with large build histories</summary>

Codefresh API rate limits apply based on your account tier. If you're syncing a very large build history (months of data on a busy account), the initial sync may hit rate limits and slow down. Start with a shorter date range to get recent data first, then extend the range in subsequent runs.

</details>

## Codefresh FAQ

<details>

<summary>Where do I find my Codefresh API key?</summary>

Log into Codefresh and go to **User Settings** (click your avatar in the bottom left). Under the **API Keys** section, click **Generate** to create a new key. Copy it immediately — Codefresh won't show it again after you leave the page.

</details>

<details>

<summary>Can I connect multiple Codefresh accounts to the same data flow?</summary>

Each Codefresh source in Coupler.io is tied to one API key and therefore one account. To combine data from multiple accounts, create a separate source for each account and use the **Append** transformation in your data flow to merge them into a single output.

</details>

<details>

<summary>Which entities update in real time and which are static?</summary>

Builds and Audits are updated continuously as your pipelines run. Entities like Pipelines, Projects, Step types, Helm repos, and Contexts are relatively static — they change only when your team updates configurations. Agents reflect current registration status. Schedule your data flow refresh frequency based on how often the data actually changes.

</details>

<details>

<summary>Can I use Codefresh data with AI tools?</summary>

Yes. Coupler.io supports AI destinations including ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. You can send Builds or Analytics reports data directly to these tools — for example, to generate a plain-language summary of your deployment health or to identify failure patterns across pipelines.

</details>

<details>

<summary>Why does the Analytics reports entity return no data even though I configured everything?</summary>

This almost always comes down to the date range not covering a complete reporting period. For example, if your granularity is set to weekly but your date range doesn't include at least one full week, Codefresh won't return a report row. Check that your date range aligns with complete periods at your chosen granularity. See the Common Issues article for more detail.

</details>

<details>

<summary>Does Coupler.io pull the actual build logs or just metadata?</summary>

The Builds entity pulls metadata — status, duration, triggered by, branch, commit SHA, and error messages. Full raw build logs are not exported. If you need log content, you'd need to access those directly in the Codefresh UI or via their API outside of Coupler.io.

</details>

<details>

<summary>Can I track which team members triggered the most builds?</summary>

Yes. The Builds entity includes a "triggered by" field. Export Builds data to Google Sheets or BigQuery, then aggregate by that field to see build volume per user. Joining with the Accounts entity on user ID will give you full name and account details alongside the build counts.

</details>

{% hint style="info" %}
For a full breakdown of available fields per entity, see [Data Overview](#codefresh-data-overview). For help with syncs that return empty data or permission errors, check [Common Issues](#codefresh-common-issues).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/project-management/codefresh.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
