> 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/best-practices.md). # Best Practices ## Recommended setup


Start with Builds as your primary entity	Builds contain the richest operational data — status, duration, branch, and trigger info. Get this entity working first before layering in Analytics reports or Audit logs.
Join Builds with Pipelines	Build records include a pipeline ID but not the pipeline name or project. Use a Join transformation in your data flow to enrich build data with pipeline metadata for readable, filterable reports.
Use Append for multi-range analytics	Codefresh Analytics reports only cover one date range per request. Use the Append transformation to combine reports from multiple periods into a single continuous dataset for trend analysis.
Scope your API key to an admin account	Entities like Accounts, Account settings, and Audits require admin access. Using an admin-generated API key from the start avoids permission errors when you add new entities later.

## Data refresh and scheduling


Set your start date close to your reporting window	Don't pull all-time build history on every sync. Set a start date that covers your actual reporting need (e.g., the last 90 days) to keep syncs fast and your destination clean.
Match analytics granularity to your reporting cadence	If you report weekly to stakeholders, set report granularity to weekly. Daily granularity on long date ranges generates a lot of rows and slows down your destination.

## Performance optimization


Separate Builds from Audit logs into different data flows	Builds update frequently; Audit logs are lower volume but may have different retention. Keeping them in separate data flows lets you set different schedules and start dates for each.
Use BigQuery for large build histories	If you're syncing months of build records from an active account, Google Sheets will hit row limits quickly. Send high-volume entities like Builds to BigQuery and use Looker Studio to visualize them.

## Common pitfalls {% hint style="danger" %} Don't skip the report granularity and date range settings when syncing Analytics reports. Leaving these blank will result in an empty sync with no error message — it'll look like the entity has no data. {% endhint %} {% columns %} {% column %} **Do** * Generate your API key from an admin account * Join Builds with Pipelines for readable reports * Test with a short date range before expanding to full history * Use BigQuery or Looker Studio for large-scale build analytics {% endcolumn %} {% column %} **Don't** * Use the same data flow for both frequently-updated and static entities * Pull all-time build history on every scheduled run * Rely on raw Build IDs in reports without joining pipeline metadata * Assume Contexts expose secret values — they only contain metadata {% endcolumn %} {% endcolumns %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.coupler.io/sources/category/project-management/codefresh/best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.