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

# Connect Engineering Events to Costory (GitHub, CI/CD, Custom API)

> Correlate cloud cost changes with GitHub deploys, CI/CD events, Savings Plan purchases, and custom events via API. Save event context and overlay events on cost charts.

Connect engineering events to Costory so you can correlate cost changes with GitHub deploys, CI/CD runs, provider commitments, and custom API events. This makes root cause analysis faster and gives your team shared context in Explorer and the [Events page](/features/events).

<Info>
  Events show up as timeline markers in Costory. You can filter by source, category, and labels to explain cost changes in seconds.
</Info>

<Frame caption="Contextualize dashboard with events">
  <img src="https://mintcdn.com/costory/9QR9mkIN8IiZz2eI/images/events.gif?s=5f9fbcec065a99732b85f30c99da7f31" alt="Costory dashboard contextualized with events on cost charts" width="1148" height="720" data-path="images/events.gif" />
</Frame>

## Supported event sources

<CardGroup cols={2}>
  <Card title="GitHub deploys" icon="github" href="/setup/events/github">
    Pull request merges, releases, and deployment metadata.
  </Card>

  <Card title="CI/CD pipelines" icon="gear" href="/setup/events/ci-cd">
    Post build and deploy events directly from your pipelines.
  </Card>

  <Card title="Custom API events" icon="calendar-plus" href="/setup/events/custom-api">
    Send any event that explains spend via the Events API.
  </Card>

  <Card title="Provider events" icon="cloud" href="/setup/events/provider">
    AWS live; Azure and GCP on the roadmap.
  </Card>
</CardGroup>

## How events work in Costory

1. **Connect a source** (GitHub, CI/CD, or API).
2. **Categorize events** as BUSINESS, TECHNICAL, or PROVIDER.
3. **Save events with context** so the date, source, labels, and description are available from the [Events page](/features/events).
4. **Overlay events on cost charts** for fast <Tooltip tip="Aligning technical or business events with cost timelines to explain why costs changed." cta="See Glossary" href="/docs/glossary#event-correlation">event correlation</Tooltip> in [Explorer](/features/cost-explorer).
5. **Share context** in saved views, dashboards, and [Cost Reports](/features/slack-reports).

## Event categories

Costory groups events into three categories so you can filter consistently across teams:

| Category      | What it represents                     | Examples                                                                                                                                                                                                                                                                                                                                                  |
| ------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **BUSINESS**  | Go-to-market or product events         | Launches, pricing changes, marketing campaigns                                                                                                                                                                                                                                                                                                            |
| **TECHNICAL** | Engineering and infrastructure changes | Deploys, incidents, migrations, CI/CD runs                                                                                                                                                                                                                                                                                                                |
| **PROVIDER**  | Cloud provider and billing changes     | <Tooltip tip="AWS's flexible commitment-based pricing." cta="See Glossary" href="/docs/glossary#savings-plans">Savings Plans</Tooltip> purchases, <Tooltip tip="A commitment to use a specific instance type for 1 or 3 years." cta="See Glossary" href="/docs/glossary#reserved-instances">Reserved Instances (RIs)</Tooltip> activations, price changes |

## Frequently asked questions

<AccordionGroup>
  <Accordion title="How fast do events appear in Costory?">
    GitHub and provider events typically appear within minutes. API events appear as soon as they are accepted by the Events API.
  </Accordion>

  <Accordion title="Can I backfill historical events?">
    Yes. Post events with historical timestamps and Costory will place them on the correct date in your cost timeline.
  </Accordion>

  <Accordion title="Do events change my cost data?">
    No. Events are metadata overlays only. They help explain costs but do not modify billing data.
  </Accordion>

  <Accordion title="Can I filter or export events?">
    Yes. Use category, label, source, and environment filters in the Events page and in Explorer views.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Add Usage Metrics" icon="chart-line" href="/setup/usage-metrics">
    Combine events with KPIs for full context.
  </Card>

  <Card title="Events" icon="calendar-days" href="/features/events">
    Save, filter, and manage event context.
  </Card>

  <Card title="Explore costs" icon="chart-area" href="/features/cost-explorer">
    See how events drive cost changes in your dashboards.
  </Card>
</CardGroup>