Getting started
1. Sign in with GitHub
Click the Quay icon in the menu bar (circular arrows). On first launch, an onboarding screen appears.
- Click Sign in with GitHub
- A code appears and is automatically copied to your clipboard
- Click Open GitHub — a browser opens to GitHub's device authorization page
- Paste the code, click Authorize, and you're connected
Alternative: Personal access token
If you prefer, click "Use a personal access token instead" during onboarding. You'll need a token with the repo scope (classic) or Contents: Read and write permission (fine-grained). Create one at github.com/settings/tokens.
2. Add a repository
Click + in the bottom toolbar:
- Existing folder — Select any local folder. If it's not a git repository, Quay initialises it automatically. If there's no GitHub remote, Quay asks for the URL.
- Clone from GitHub — Paste a GitHub URL and choose a destination. Quay clones it (shallow by default; check "Full clone" for history). If the folder already exists and matches the remote, Quay adds it directly without re-cloning.
3. Sync
- Click the sync button on any repo row to sync it
- Click Sync All to sync everything at once
- A green dot means the last sync succeeded
- A blue-green dot means there are local changes
- A red dot means it failed — click the error icon for details
How sync works
Fetch latest changes from GitHub. Pull with fast-forward only (no merge commits). Safety checks — refuses files over 50 MB or unignored secrets (.env, .pem, .key, etc.). Stage all changes. Commit with an auto-generated message. Push to GitHub.
If local and remote have diverged, Quay reports a conflict and offers four resolution strategies:
- Merge — creates a merge commit combining both sides
- Rebase — replays your local commits on top of the remote
- Fresh branch — saves your work to a new branch and resets the original to match GitHub
- Reset — discards local changes and resets to the GitHub version
GitHub activity
Each repo row shows the number of open issues and pull requests. Click the counts to open the corresponding page on GitHub. Counts refresh automatically after each sync and once per hour.
Repos also display ahead/behind commit counts (e.g. ↑2 ↓3) so you can see at a glance whether you have unpushed commits or need to pull. A CI status badge shows the latest GitHub Actions result — click it to open the Actions page.
Settings
Click Manage... in the bottom toolbar:
- Launch at login — Start Quay when you log in
- Change GitHub Connection — Sign in with a different account or reconnect an expired session
- Reset Quay — Remove all repos, your credentials, and sync history
Where data is stored
All data lives inside the macOS app sandbox container:
~/Library/Containers/Quay/| File | Contents |
|---|---|
credential | Your GitHub credential (file permissions 0600) |
config.json | Tracked repos, bookmarks, sync state |
events/*.json | Sync history per repo |
Your credential is stored locally and never sent anywhere except GitHub's API and to git via a temporary script that is deleted after each sync.
Troubleshooting
"Git not found" — Install Xcode Command Line Tools: xcode-select --install
"Authentication failed" — Your GitHub connection may have expired. Go to Settings > Change GitHub Connection to sign in again.
"Local and remote have diverged" — Click the error icon and choose a resolution strategy: Merge, Rebase, Fresh Branch, or Reset.
"File is too large" — Remove the file or add it to .gitignore.
"Unignored secrets found" — Add the flagged files to .gitignore.