Ramille help

Install Ramille

Ramille runs on macOS 12 or later. It is one universal app for Intel and Apple Silicon Macs.

Ramille uses the Git installed on your Mac, version 2.38 or later. If Git is missing or too old, Ramille tells you so when it starts. You can install Apple’s tools with xcode-select --install, or Git with brew install git.

First install

1. Open the downloaded Ramille.dmg file.
2. Drag Ramille into the Applications folder.
3. Open Ramille from Applications. The app is signed and notarized by Apple.

Open your first repository

The home screen lists your favorites and recent repositories. From there:

• ⌘O opens a repository already on your Mac;
• “Clone a repository…” asks for the repository address (HTTPS or SSH, without a password or token in it), the parent folder and the folder name;
• “Initialize a repository…” creates a new one.

Each repository has four screens: History, Changes, Sync and Pull requests. ⌘K opens the command palette, which gives access to every command.

Updates

Ramille updates itself with Sparkle. Once a day, it checks whether a new version exists. When one is available, it shows the release notes and installs the update only after you click. Every update is signed, and Sparkle checks the signature before installing it.

To check right away: Ramille menu › “Check for Updates…”, also in the palette (⌘K).

In Settings › Updates you can turn the daily check off, see the installed version and check now. The release notes of each version are on the What’s new page.

Connect GitHub

Ramille reads and writes on GitHub through its own GitHub App. You do not need to create a token.

1. Open Settings › Accounts (also from the palette, or from “Connect a host to see your PRs…” on the home screen).
2. Click “Sign in to GitHub…”. Ramille shows a code and opens github.com/login/device in your browser.
3. Enter the code (the “Copy code” button helps), then authorize the app.
4. Install the app on the accounts and organizations whose repositories you want to see. Ramille offers “Install the GitHub App” and “Manage GitHub installations”.
5. Back in Ramille, “Test connection” should show your GitHub username.

Permissions requested

When the app’s permissions change, GitHub asks each account or organization where it is installed to accept them. Until then, GitHub refuses writes (error 403). For your account, go to github.com/settings/installations, open the app, then “Review request” and “Accept”. For an organization, do the same from the organization’s settings › GitHub Apps.

If GitHub says the app is not installed on an account or organization, install it there from its GitHub page, then refresh. If GitHub refuses the token, sign in again in Settings › Accounts.

GitHub Enterprise Server works with a personal access token with the repo and read:org scopes. Ramille then shows pull requests in read-only mode.

Connect GitLab

For gitlab.com or your own GitLab server, Ramille uses a personal access token.

1. In Settings › Accounts › GitLab, click “Create a GitLab token…”.
2. Give the token the api and read_user scopes and a short expiry date.
3. Paste the token into Ramille, then save and test.

With GitLab, Ramille can create merge requests. To read and review them, Ramille opens them in your browser. Git operations (fetch, pull, push) work as with any other host.

Connect Azure DevOps

The main way is a personal access token (PAT) created for your organization.

1. In Settings › Accounts › Azure DevOps, enter your organization name.
2. Click “Use a personal access token (PAT)”, then open the token page on dev.azure.com and choose “New Token”.
3. Choose your organization and select the scopes below. Keep the expiry short.
4. Copy the token: Azure DevOps shows it only once.
5. Paste it into Ramille, then “Save and test”.

“Code: Read” is enough to read without commenting or voting. When the token expires, create a new one and use “Replace token…”.

If Azure DevOps refuses a write (403), the token lacks “Code: Read & write”. If it refuses the token (401), the token has expired, was revoked or was created for another organization. Your account also needs the right to contribute to the repository’s pull requests. Ramille never bypasses a branch policy.

“Sign in with Microsoft Entra…” is only for organizations backed by a Microsoft Entra directory (company or school). Microsoft refuses personal accounts (outlook.com, hotmail.com): use a personal access token instead.

Azure DevOps Server (on premises) works with a PAT with “Code: Read & write”. Ramille then shows pull requests in read-only mode.

Connect Bitbucket

With Bitbucket, Ramille shows pull requests, their changes, discussions and CI status. Commenting, reviewing and merging from Ramille are not available yet: open the pull request in your browser.

Bitbucket Cloud (bitbucket.org)

1. Settings › Accounts › Bitbucket Cloud › “Open the Atlassian API tokens page…”.
2. Choose “Create API token with scopes”, Bitbucket app. A token without scopes is refused.
3. Select read:user:bitbucket, read:pullrequest:bitbucket and read:repository:bitbucket. To create pull requests, add write:repository:bitbucket and read:permission:bitbucket. Keep the expiry short.
4. In Ramille, enter the email address of your Atlassian account (not your Bitbucket username) and the token, then “Save and test”.

Bitbucket Data Center

1. Settings › Accounts › Bitbucket Data Center: enter the server’s web address as your browser shows it, path included (for example https://git.example.com/bitbucket). If your SSH addresses use another host than the same host on port 7999, fill in the SSH hosts field. Then “Add server”.
2. Click “Check”. Ramille needs Bitbucket Data Center 8.19 or later.
3. In Bitbucket: your avatar › Manage account › HTTP access tokens › Create token, with Read permission on projects and repositories.
4. In Ramille, enter your Bitbucket username and the token, then “Save and test”.

Company network

Ramille uses the proxy set in Git (git config --global http.proxy http://proxy:port). A proxy set only in your shell is not seen when Ramille is opened from the Finder. If a server’s certificate is refused, open its address in Safari; if Safari warns you, ask your IT team for the internal certificate authority and add it to the System keychain.

Several accounts per host

You can connect several accounts on the same host, for example a personal and a work GitHub account. In Settings › Accounts, use “Add a … account”.

For each repository, Ramille picks the account in this order:

1. the account you chose for this repository;
2. otherwise, the account that has access to the owner or organization in the remote address;
3. otherwise, the host’s default account.

To choose by hand, click “as …” on a pull request screen and pick an account for this repository.

If your remotes use an alias from ~/.ssh/config (for example git@github-work:org/repo.git), Ramille asks ssh for the real host name, without connecting, so it can recognize the host and pick the right account. It also applies your Git insteadOf and pushInsteadOf rules. It reads them and never changes them.

SSH

Ramille runs the system’s ssh, so your ~/.ssh/config, your SSH agent and core.sshCommand apply as in Terminal. Agents set with IdentityAgent, such as 1Password or Secretive, work too.

Passphrase

If your key has a passphrase, Ramille asks for it in its own dialog and does not keep it. Check “Add to SSH agent” to let macOS store it in your Keychain, so you are not asked again.

Host fingerprint

The first time you connect to a server, Ramille shows the SHA256 fingerprint of its host key and asks whether to trust it. If you accept, the key is added to ~/.ssh/known_hosts, as ssh would do.

• For github.com, gitlab.com, bitbucket.org and ssh.dev.azure.com, Ramille compares the fingerprint with the values these hosts publish. If it does not match, Ramille refuses the connection.
• For your own server, check the fingerprint with its administrator before trusting it.
• If a host key you already trusted has changed, Ramille always refuses and shows the ssh-keygen -R command to remove the old key once you have checked the new one.

Ramille does not turn off host key checking, even if your SSH configuration sets StrictHostKeyChecking no.

macOS Keychain

Ramille keeps your account tokens and AI keys in the macOS Keychain, one item per account. It never shows a token. For HTTPS remotes, it also uses the Git credential helpers you already have.

macOS may ask for access to a Ramille item with your “login” keychain password. The usual causes: the item was created by another copy of the app, access was granted once (“Allow”) rather than for good (“Always Allow”), or your login keychain no longer has the same password as your session.

When the Keychain refuses access, the account shows “Check” in Settings › Accounts, with two buttons:

• “Allow access…”: macOS shows its request. Enter your session password and choose “Always Allow”.
• “Reconnect” (GitHub, Microsoft Entra) or “Replace token…” (personal tokens): the new token replaces the old one.

If macOS refuses your session password, open Keychain Access. If you know your old password, use Edit › “Change Password for Keychain "login"”. Otherwise, Keychain Access › Settings › “Reset My Default Keychain”, log out and back in, then reconnect your accounts in Ramille.

Trial and license

You can try Ramille for free for 14 days of use, with no credit card. Only the days you open the app count. After the trial, your history, diffs and pull requests stay readable. A license is needed to change your repositories.

A license is a one-time purchase of €49, excluding VAT. It includes:

• every 1.x version, with all of its updates;
• any major version released within 12 months of your purchase, with all of its updates;
• use on up to 3 Macs.

Polar sells the licenses on our behalf as merchant of record: it handles payment, invoice and the VAT of your country. After your purchase, you receive your license key by email and enter it in Ramille. For any question about a purchase, write to us. The full terms are in the terms of sale and license agreement.

Keyboard shortcuts

⌘/ lists the shortcuts of the current screen, with a search field. ⌘K opens the palette.

In a text field, ⌘Z and ⇧⌘Z undo and redo your typing. Outside a field, they undo and redo the last Git action.

Privacy in short

• Your repositories do not go through any Ramille server. The app talks directly to your Git hosts.
• No analytics and no crash reports are sent. The usage log stays on your Mac.
• Tokens and AI keys are kept in the macOS Keychain.
• AI features are optional. Nothing is sent before you see a preview and click to send. You can use a local model (Ollama, LM Studio) instead of a remote provider.
• The daily update check downloads a file from GitHub, with no account and no repository data.

Details are in the privacy policy.

Report a problem

Ramille keeps a usage log on your Mac. Nothing is sent automatically.

1. Reproduce the problem.
2. Choose Help › “Send a report…” (also in Settings › Updates and in the palette).
3. Ramille opens a draft in Mail with the report attached. Without Mail, copy the report or show the file in the Finder.
4. Read the report, describe what you did, what you expected and roughly when it happened, then send it to ramille@glabs325.com.

The log keeps technical data: commands run, screens shown, Git actions with their duration and result, errors. It never keeps the content of your files, diffs, commit messages or Git arguments. Tokens and email addresses are masked, and paths in your home folder become ~/…. In Settings › Updates you can turn the log off, open its folder or clear it.