GitHub Actions Integration

CICosts integrates with GitHub Actions to receive workflow data and provide real-time cost tracking. This page covers advanced integration options.

How It Works

GitHub App

The CICosts GitHub App:

1. Receives webhooks when workflows start/complete
2. Fetches job details via GitHub API
3. Calculates costs based on runner usage
4. Updates your CICosts dashboard

Required Permissions

The GitHub App requests:

Permission	Access	Purpose
Actions	Read	View workflow runs and jobs
Metadata	Read	View repository information

Data Flow

GitHub Actions → Webhook → CICosts API → Dashboard
     ↓
Workflow Run → Event → Cost Calculation → Display

Advanced Configuration

Workflow Annotations

Add cost info directly to your workflow runs:

name: CI

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run build
        run: npm run build

      # Add cost annotation
      - name: Get CICosts Summary
        if: always()
        uses: cicosts/action-summary@v1
        with:
          token: ${{ secrets.CICOSTS_API_KEY }}

This adds a cost summary to your workflow run:

💰 CICosts Summary
Run cost: $2.34
Avg for this workflow: $2.15 (+8.8%)
Month-to-date: $1,247.00

Cost Badges

Add a cost badge to your README:

[![CI Costs](https://api.cicosts.dev/v1/badge/my-org/my-repo/ci.yml)](https://cicosts.dev/dashboard)

Result:

PR Comments

Automatically comment on PRs with cost impact:

name: PR Cost Check

on: pull_request

jobs:
  cost-check:
    runs-on: ubuntu-latest
    steps:
      - uses: cicosts/pr-comment@v1
        with:
          token: ${{ secrets.CICOSTS_API_KEY }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

PR Comment:

## 💰 CICosts Report

This PR's CI runs have cost: **$12.45**

| Workflow | Runs | Cost |
|----------|------|------|
| ci.yml | 5 | $8.90 |
| lint.yml | 5 | $3.55 |

Compared to main branch: **+15%** higher than average

[View in CICosts →](https://cicosts.dev/dashboard)

Optimizing Based on CICosts Data

Runner Selection

Use CICosts data to choose runners:

jobs:
  build:
    # Start with smaller runner
    runs-on: ubuntu-latest

    # CICosts showed this job needs more resources
    # runs-on: ubuntu-latest-4-core

Conditional Workflows

Skip expensive workflows when not needed:

name: Full Test Suite

on:
  push:
    branches: [main]
  pull_request:
    # Only run on PRs with specific labels
    types: [labeled]

jobs:
  full-tests:
    if: github.event_name == 'push' || contains(github.event.pull_request.labels.*.name, 'run-full-tests')
    runs-on: ubuntu-latest-16-core
    steps:
      - run: npm run test:full

Matrix Optimization

Based on CICosts analysis:

strategy:
  matrix:
    # Before: Full matrix (9 jobs, $X/run)
    # os: [ubuntu, windows, macos]
    # node: [16, 18, 20]

    # After: Optimized matrix (5 jobs, 44% savings)
    include:
      - os: ubuntu-latest
        node: 16
      - os: ubuntu-latest
        node: 18
      - os: ubuntu-latest
        node: 20
      - os: windows-latest
        node: 18
      - os: macos-latest
        node: 18

GitHub Actions in CICosts

Viewing Workflow Data

In the CICosts dashboard:

1. Go to Workflows tab
2. See all workflows across repos
3. Click any workflow for details

Filtering

Filter workflow runs by:

• Status (success, failure, cancelled)
• Trigger (push, pull_request, schedule)
• Branch
• Date range

Drill-Down

For each workflow run:

• View job breakdown
• See runner types used
• Check step-by-step timing
• Compare to averages

Troubleshooting

Runs Not Appearing

1. Check GitHub App installation

   • Verify the app is installed on the repo
   • Confirm Actions read permission

2. Check webhook delivery

   • Go to GitHub → Settings → Apps → CICosts
   • View recent deliveries
   • Check for errors

3. Wait for processing

   • New runs may take 1-2 minutes to appear
   • Historical runs are processed on installation

Cost Calculation Issues

1. $0 cost shown

   • May be self-hosted runner
   • Check runner labels in workflow

2. Cost seems wrong

   • Verify runner type detection
   • Check billable time vs. elapsed time

Webhook Errors

If GitHub shows webhook failures:

1. Check CICosts status page
2. Wait for auto-retry
3. Contact support if persistent

---

See also: FAQ →