Skip to main content

Connecting GitHub

CICosts uses GitHub OAuth and a GitHub App to securely access your workflow data. This guide explains how the connection works and what permissions are required.

How CICosts Connects​

CICosts uses two types of GitHub integrations:

1. OAuth App (User Authentication)​

When you sign in with GitHub, we use OAuth to:

  • Authenticate your identity
  • Access your email and username
  • List organizations you belong to

Scopes requested:

  • read:user - Read your profile information
  • user:email - Access your email address
  • read:org - List your organizations

2. GitHub App (Repository Access)​

The CICosts GitHub App is installed on your organizations to:

  • Receive webhooks when workflows run
  • Fetch workflow run metadata
  • Calculate costs based on runner usage

Permissions requested:

  • actions: read - View workflow runs and jobs
  • metadata: read - View repository names and metadata

Installation Steps​

Installing on Personal Repositories​

  1. Go to cicosts.dev/dashboard
  2. Click "Add Organization" or the + button
  3. Select your personal account from the list
  4. Choose which repositories to track
  5. Click Install

Installing on Organizations​

You must be an organization owner or have admin permissions to install the GitHub App.

  1. Go to cicosts.dev/dashboard
  2. Click "Add Organization"
  3. Select the organization from the list
  4. Choose repository access:
    • All repositories - Automatically tracks new repos
    • Selected repositories - Manually choose repos
  5. Click Install
Organization approval

Some organizations require admin approval for app installations. If you see a "Request" button instead of "Install", your request will be sent to org admins.

Managing App Permissions​

View Current Installations​

  1. Go to GitHub Settings → Applications → Installed GitHub Apps
  2. Find CICosts in the list
  3. Click Configure to view or modify

Change Repository Access​

  1. Open the GitHub App configuration (steps above)
  2. Under "Repository access", select your preference
  3. Click Save

Changes take effect immediately.

Revoke Access​

To disconnect CICosts from an organization:

  1. Go to GitHub Settings → Applications → Installed GitHub Apps
  2. Find CICosts
  3. Click Configure → Uninstall
Data retention

After uninstalling, your historical cost data remains in CICosts for 30 days (Free) or 1 year (Pro), but no new data will be collected.

Multiple Organizations​

CICosts supports tracking multiple organizations from a single account:

  1. Install the GitHub App on each organization
  2. Use the org switcher in the dashboard header to switch between orgs
  3. View aggregated costs across all orgs on the main dashboard

Agency Use Case​

If you manage GitHub organizations for clients:

  1. Install CICosts on each client's organization
  2. Track costs per client for accurate billing
  3. Set per-org budget alerts to prevent overruns

Security Considerations​

What CICosts CAN access​

  • Workflow run metadata (times, status, runner labels)
  • Job information (names, durations)
  • Repository names and visibility
  • Organization membership

What CICosts CANNOT access​

  • Your source code
  • Repository contents (files, commits)
  • Secrets or environment variables
  • SSH keys or deploy keys
  • Billing information or credit cards

Data Privacy​

  • We only store workflow metadata needed for cost calculation
  • Data is encrypted at rest and in transit
  • We never share your data with third parties
  • You can request data deletion at any time

Next: Your First Dashboard →