GitHub Integration

The GitHub integration enables Cloud ex Machina to:

• Create and manage issues for cost optimization opportunities
• Open pull requests with infrastructure-as-code changes generated by the AI agent
• Read repository files to inform remediation analysis
• List organization members for ticket assignment

Choosing the Right Connection Method

Cloud ex Machina supports three ways to connect to GitHub. Pick the one that matches your security posture and constraints:

Method	Auth Mechanism	Best For	Token Type
GitHub App (OAuth)	User OAuth via Cloud ex Machina App	Quick setup, individual user grants the app access	OAuth access token
GitHub App (Installation)	Org-wide installation of Cloud ex Machina App	Production — no per-user re-auth, audit-friendly	Installation token (auto-renewed)
GitHub PAT	Personal Access Token from a dedicated service account	Environments where third-party Apps are restricted, or self-hosted GitHub Enterprise Server	Long-lived PAT

Recommended Path

The GitHub App (Installation) method provides the strongest security (scoped permissions, automatic token rotation, clear audit trail) and the simplest user experience (one-time install). Choose it whenever your organization's policies allow third-party GitHub Apps.

Choose the PAT method when your security policy forbids third-party Apps or when you operate on GitHub Enterprise Server without App support.

---

Method 1: GitHub App (OAuth)

In this mode, an individual GitHub user authorizes the Cloud ex Machina App on their own account. The integration acts on behalf of that user.

Permissions Granted

When the user clicks Authorize, GitHub requests the following OAuth scopes:

Scope	Purpose
repo	Full access to repos the user can access — read content, create branches, commit files, open pull requests
read:org	List organizations and members the user belongs to (for ticket assignment)
read:user	Resolve GitHub username from email (for issue assignees)
user:email	Access the user's verified email addresses

Setup

1. In Cloud ex Machina, go to Settings → Integrations
2. Find GitHub in the list and click Connect
3. You will be redirected to GitHub to authorize the Cloud ex Machina App
4. Click Authorize
5. Configure Owner (organization or user) and Repository in the integration settings modal

Per-User Authorization

This method ties the integration to a specific user account. If that user leaves the company or has their permissions revoked, the integration stops working. Avoid for production — use the Installation method or a PAT from a service account instead.

---

Method 2: GitHub App (Installation)

In this mode, an organization administrator installs the Cloud ex Machina App org-wide. The integration uses installation tokens, which are scoped to the org and rotate automatically — no per-user OAuth flow.

Permissions Granted

When an admin installs the Cloud ex Machina App, GitHub requests the following repository permissions (granted at the org level, applicable to all selected repos):

Permission	Access Level	Used For
Contents	Read	Read repository files (Terraform, code) for remediation analysis
Issues	Read & Write	Create and update issues for cost optimization opportunities
Pull requests	Read & Write	Open PRs with AI-generated infrastructure changes
Metadata	Read	Mandatory — list repos accessible to the installation
Members	Read	List org members for ticket assignment

And the following organization permissions:

Permission	Access Level	Used For
Members	Read	List organization members

Setup

1. In Cloud ex Machina, go to Settings → Integrations
2. Find GitHub App in the list and click Connect
3. You will be redirected to GitHub to install the Cloud ex Machina App
4. Choose All repositories or Only select repositories (recommended — pick only the IaC repos)
5. Click Install
6. Configure Owner and Repository in the integration settings modal

No Per-User Re-Auth

Once installed, the integration works independently of any user account. The token is renewed automatically every hour. If you need to revoke access, simply uninstall the App from your GitHub organization settings.

---

Method 3: GitHub PAT

The PAT method uses a long-lived Personal Access Token generated from a dedicated GitHub user account (a "machine user"). It is the right choice for environments where third-party Apps are not allowed or supported.

Use a Service Account, Not a Personal Account

Always create a dedicated GitHub user account for this PAT — never use a token tied to an individual employee's personal account. See the Service Account Setup section below.

Permissions Granted

You can use either a classic PAT or a fine-grained PAT. Pick the one that matches your org's security policies.

Option A — Classic PAT scopes

Scope	Purpose
repo	Full access to private and public repos — read content, create branches, commit files, open pull requests, read PR metadata
read:org	List organization members, repos, and GitHub Projects
read:user	Resolve GitHub username from email (for issue assignees)
user:email	Access verified emails (required by read:user)

Option B — Fine-grained PAT permissions

Fine-grained PATs are scoped to a single organization at creation time. Pick this if your org enforces fine-grained PATs.

Permission	Access Level	Used For
Contents	Read & Write	Read files, create branches, commit files
Pull requests	Read & Write	Create and list PRs
Issues	Read & Write	Create and list issues
Metadata	Read	Mandatory — list repositories
Members	Read	List organization members

Fine-grained Limitation

A fine-grained PAT only works for the org selected at creation. If you need to cover multiple orgs with one token, use a classic PAT instead.

Service Account Setup

GitHub has no native "service account" concept, so the standard pattern is to create a dedicated GitHub user account for the integration. This is officially called a Machine User and is accepted by GitHub's Terms of Service.

Step 1: Create the Service Account

1. Create a new GitHub account using a shared team email (e.g., cxm-bot@yourcompany.com — ideally a distribution list or alias controlled by your IT/security team, never a personal mailbox)
2. Set a strong password stored in a team password manager
3. Enable 2FA with a TOTP secret shared in your team vault (Authy, 1Password, etc.) — most orgs require 2FA. Do not use a personal phone.
4. Verify the email address — GitHub sends security notifications (token created/revoked/expired) that must be read by your security/devops team

Seat Cost

On GitHub Free, additional accounts are free. On GitHub Team/Enterprise, this account consumes one paid seat.

Step 2: Invite the Service Account to Your Organization

1. Sign in to GitHub as an organization owner
2. Navigate to your organization's People tab
3. Click Invite member and add the service account email
4. Assign the Member role (avoid Owner unless strictly necessary)
5. Once the service account accepts the invitation, grant it access to the specific repositories Cloud ex Machina will operate on (via Settings → Teams or repo-level Settings → Collaborators)

Step 3: Generate the PAT

1. Sign in to GitHub as the service account
2. Go to Settings → Developer settings → Personal access tokens
3. For a classic PAT:
   • Click Tokens (classic) → Generate new token (classic)
   • Note: Cloud ex Machina Integration
   • Expiration: 90 days (recommended), set a calendar reminder for renewal
   • Scopes: Check repo, read:org, read:user, user:email
   • Click Generate token
4. For a fine-grained PAT:
   • Click Fine-grained tokens → Generate new token
   • Resource owner: Select your organization
   • Repository access: Select only the repos Cloud ex Machina will use
   • Permissions: Set the permissions listed in Option B
   • Click Generate token
5. Critical: Copy the token immediately — it is shown only once. Store it in a password manager or secrets vault before leaving the page.

Token Security

The PAT is displayed only once at creation. If you lose it, you must generate a new token and reconnect the integration. Never commit a PAT to a repository or share it via insecure channels.

Setup in Cloud ex Machina

1. Go to Settings → Integrations
2. Find GitHub PAT in the list and click Connect
3. Paste the PAT into the connection dialog
4. Click Save
5. Configure Owner (the organization the service account is a member of) and Repository in the integration settings modal

Limitations vs the GitHub App

• No automatic PR-merged webhook routing: Pull requests merged in GitHub will not automatically transition opportunities to "Done" — transition them manually if needed.
• Rate limit: 5,000 requests/hour per PAT (vs 15,000 for a GitHub App). Monitor usage if you operate on many repos.
• Account dependency: If the service account is suspended or removed from the org, the integration breaks. Make sure the account is owned by your security/devops team, not an individual.

---

Troubleshooting

"No GitHub connection configured"

Cause: The webhook from GitHub arrived but no matching connection exists in Cloud ex Machina.

Fix: Reconnect the integration, or check that the connection was not accidentally deleted.

"Token is invalid or expired"

Cause: The OAuth token, installation token, or PAT has expired or been revoked.

Fix:

• OAuth / App Installation: Reconnect from the Cloud ex Machina integrations page
• PAT: Generate a new PAT from the service account and update the connection

"Repository not found"

Cause: The configured owner/repo does not match any repository accessible to the connection.

Fix:

• Verify the owner and repository names are correct (case-sensitive)
• For PAT: confirm the service account has been granted access to the target repo
• For App Installation: re-check the Repository access setting in the GitHub App installation

Pull Requests Are Not Being Created

Cause: The token lacks write permissions on contents or pull requests.

Fix:

• PAT (classic): Ensure repo scope is checked (full access required)
• PAT (fine-grained): Ensure Contents: Read & Write and Pull requests: Read & Write are granted
• App Installation: Re-install the App and verify the listed permissions match the ones in Method 2

---

Security Best Practices

1. Prefer the GitHub App (Installation) for production deployments
2. Never use a PAT from an individual user account — always use a dedicated service account
3. Store PATs in a password manager or secrets vault — never in a repo, ticket, or chat message
4. Rotate PATs every 90 days at minimum, before expiration
5. Use fine-grained PATs when your org's security policy allows them — they offer better scoping than classic PATs
6. Grant the minimum required repository access — list specific repos rather than "all repositories" wherever possible
7. Monitor GitHub audit logs for unexpected activity by the integration's account
8. Use a shared team email for the service account, not an individual's email

---

Next Steps

• Learn about other available integrations in Integrations Overview
• Configure additional providers to centralize your workflows