GitHub Access at Tractorbeam

Tractorbeam uses GitHub to host our source code. GitHub access is managed through Okta SSO with automatic team synchronization.

How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Okta (Source of Truth)                            │
│                                                                             │
│  Users ──── SAML SSO ────► GitHub (authentication)                          │
│                                                                             │
│  Groups ─── Team Sync ───► GitHub Teams (membership synced automatically)   │
│             ├── Engineering     → engineering team                          │
│             ├── Platform-Admins → platform-admins team                      │
│             ├── Security        → security team                             │
│             └── Project-*       → project-* teams                           │
└─────────────────────────────────────────────────────────────────────────────┘

Before Your First Login

1. Add Tractorbeam Email to Your GitHub Account

You can use your personal GitHub account, but you must add your @tractorbeam.ai email address:

1. Go to GitHub Email Settings
2. Add your yourname@tractorbeam.ai email
3. Verify it via the confirmation email

Why this matters: GitHub notifications for the tractorbeamai organization are restricted to verified @tractorbeam.ai email addresses. Without this, you won't receive any email notifications for issues, PRs, or mentions.

2. Verify Okta Access

You must have an active Okta account at Tractorbeam. If you can log into tractorbeam.okta.com, you're all set.

3. Set Up Git Authentication

Use the GitHub CLI to configure SSH authentication:

brew install gh
gh auth login

Select "GitHub.com" → "SSH" → follow the prompts. This handles SSH key generation, upload, and SSO authorization in one step.

Joining the tractorbeamai Organization

No tickets or requests needed. GitHub access is automatic through Okta:

1. Go to github.com/tractorbeamai
2. Click "Sign in with SAML"
3. Authenticate through Okta
4. You're now a member of the organization

Your team memberships sync automatically from your Okta groups. There's typically a short delay (up to 1 hour) for team sync after your first login.

Getting Access to Repositories

Repository access is controlled through GitHub Teams, which are synced from Okta groups.

Teams and Their Access

Okta Group	GitHub Team	Typical Access
Engineering	engineering	Most repositories (read/write)
Platform-Admins	platform-admins	Infrastructure repos (admin)
Security	security	Security-sensitive repos
Project-Carlyle	project-carlyle	Carlyle project repositories
Project-Mailman	project-mailman	Mailman project repositories

To Get Access to a Specific Repository

1. Ask your manager which Okta group grants access to the repository
2. Request group membership through your manager or IT
3. Once added to the Okta group, GitHub team membership syncs automatically

For Admins: Granting Repository Access

1. Ensure the user is in the correct Okta group
2. In GitHub, navigate to the repository → Settings → Collaborators and teams
3. Add the appropriate team with the desired permission level

Authentication

SSH Keys (Recommended)

The easiest way to set up SSH is with the GitHub CLI:

gh auth login

If you already have an SSH key and need to authorize it for the org:

1. Go to GitHub SSH settings
2. Click "Configure SSO" next to your SSH key
3. Click "Authorize" for tractorbeamai

Personal Access Tokens

For automation and CI, use fine-grained personal access tokens:

1. Go to GitHub Tokens
2. Generate new token (Fine-grained)
3. Set resource owner to "tractorbeamai"
4. Select only the repositories and permissions needed
5. Click "Configure SSO" and authorize for tractorbeamai

Common FAQs

I logged in but can't see any repositories

Your team memberships may not have synced yet. Team sync can take up to 1 hour. If it's been longer:

1. Sign out of GitHub completely
2. Clear your browser cookies for github.com
3. Sign in again through Okta SSO
4. If still not working, verify your Okta group memberships with IT

I need access to a repository my team doesn't have

1. Contact the repository owner or your manager
2. They can either:
   • Add your existing team to the repository
   • Request you be added to a team that already has access

How do I create a new repository?

All organization members can create repositories:

1. Go to github.com/new
2. Set owner to "tractorbeamai"
3. Choose visibility (private recommended for new projects)
4. Create the repository
5. Add appropriate teams for access

New repositories automatically have:

• Dependabot alerts enabled
• Secret scanning enabled
• Push protection for secrets

Why can't I force push to main?

Production repositories have branch protection that prevents force pushes and branch deletion on main. This is a safety net, not a process barrier. If you need to fix a broken main branch, contact Platform-Admins.

I'm getting "SAML SSO session expired" errors

Re-authenticate through Okta:

1. Go to tractorbeam.okta.com
2. Click the GitHub app tile
3. This refreshes your SAML session

For CLI tools, you may need to re-authorize your token or SSH key for SSO.

How do I recover access without my MFA device?

Since authentication goes through Okta, contact IT to reset your Okta MFA. GitHub-specific recovery codes are not applicable with SAML SSO.

What's the difference between Employees and Engineering teams?

• Employees: All full-time employees. Basic org membership.
• Engineering: Engineering team members. Has write access to most code repositories.
• Contractors: Contract workers. Similar to Employees but separate for compliance.

You may be in multiple teams based on your role.

For Platform Admins

Team Infrastructure

• Teams are created by Terraform (github/main.tf)
• Team membership is synced from Okta groups
• Team-to-Okta-group linking is a one-time manual step per team

Adding a New Team

1. Add to data/groups.json with "github_team": true
2. Run terraform apply in the github/ directory
3. Link to Okta group in GitHub UI:
   • Go to github.com/orgs/tractorbeamai/teams/{team-slug}
   • Settings → Sync group → Select matching Okta group

Organization Settings

Managed in github/main.tf:

• Default repository permission: Read
• Web commit signoff required: Yes
• Secret scanning: Enabled for new repos
• Dependabot: Enabled for new repos

Domain Verification and Email Restrictions

The tractorbeam.ai domain is verified with GitHub (DNS TXT records in cloudflare/records.tf).

Email notifications are restricted to verified @tractorbeam.ai addresses. This is configured manually in GitHub:

1. Go to Organization Security Settings
2. Under "Verified and approved domains", ensure tractorbeam.ai shows as verified
3. Under "Notification preferences", enable "Restrict email notifications to only approved or verified domains"

This setting isn't available in the Terraform provider, so changes must be made in the UI.

Production Repository Protections

The internal-infra repository has additional protections:

• Cannot force push to main
• Cannot delete main branch

To add a repository to production protections, add it to local.production_repos in github/main.tf.