GitHub Integration

Connect your GitHub account to Astrolabe for native desktop access to repositories, releases, organizations, and GitHub Actions workflows.

Features

• OAuth Authentication: Secure one-click connection with scoped permissions
• Repository Management: View and manage all your repositories and organizations
• Release Creation: Create GitHub releases directly from the desktop app
• Workflow Triggers: Trigger GitHub Actions workflows with one click
• Organization Access: Manage repositories across multiple organizations
• API Integration: Full GitHub REST API v3 support

Prerequisites

• Astrolabe v0.1.12 or later
• Active GitHub account
• macOS 15.0 or later

Setup

Option 1: OAuth (Recommended)

Option 2: Personal Access Token

Usage

Linking a Repository

Creating Releases

Viewing Release History

• View all releases for a repository
• See release dates, tag names, and notes
• Access release assets and download links
• View commit counts between releases

Triggering Workflows

Organization Repositories

For organization repositories:

1. Organizations are automatically detected during OAuth
2. Organization repos appear in the repository selector
3. You can manage repos based on your org permissions
4. Organization membership is cached locally

API Capabilities

With the GitHub integration, Astrolabe can:

• List all user repositories (public + private)
• Get repository details (stars, forks, language, etc.)
• List organizations you're a member of
• List organization repositories
• Get authenticated user info
• Create releases with markdown notes
• Trigger workflows (requires GitHub CLI)

Troubleshooting

OAuth Fails to Complete

Issue: Browser redirects but token isn't saved.

Solution:

• Ensure Astrolabe is running when you authorize
• Check the redirect URI is astrolabe://oauth/callback/github
• Try restarting and re-authorizing

Repositories Not Loading

Issue: Repository selector is empty after authentication.

Solution:

• Verify token has repo and read:user scopes
• Check you have repositories in your GitHub account
• Re-authenticate to refresh permissions

Release Creation Fails

Issue: "Not a GitHub repository" error.

Solution:

• Ensure your local repository has a github.com remote origin
• Run git remote -v to verify
• Repository must be pushed to GitHub first

Workflow Trigger Fails

Issue: Can't trigger GitHub Actions workflows.

Solution:

• Install GitHub CLI: brew install gh
• Run gh auth login to authenticate
• Ensure workflows have workflow_dispatch trigger

Security

• OAuth tokens stored encrypted via Tauri plugin-store
• Personal access tokens never leave your machine except in API calls to GitHub
• Scopes are minimally required (repo, read:user, read:org)
• Deep link callbacks use secure astrolabe:// protocol
• Token refresh not available (GitHub doesn't support OAuth refresh tokens)

API Reference

Astrolabe uses these GitHub REST API v3 endpoints:

• OAuth Token Exchange: POST /login/oauth/access_token
• Get User: GET /user
• List Repos: GET /user/repos
• Get Repo: GET /repos/:owner/:repo
• List Organizations: GET /user/orgs
• List Org Repos: GET /orgs/:org/repos

All API calls include:

• Authorization: Bearer {token} header
• Accept: application/vnd.github+json
• X-GitHub-Api-Version: 2022-11-28
• User-Agent: Astrolabe/1.0

GitHub CLI Integration

For advanced features, Astrolabe integrates with GitHub CLI:

# Install GitHub CLI
brew install gh

# Authenticate
gh auth login

# Trigger workflows from Astrolabe UI
# (Astrolabe runs: gh workflow run <workflow-name>)

Support

Need help with GitHub integration?

• GitHub Issues
• Documentation
• Email: hey@entro314.com

Related Documentation

• OAuth Setup Guide
• Release Management
• Service Connections Overview