📚 Help › Getting Started

Getting Started

Welcome to Isurus, a self-hosted Mercurial forge by Leafscale, LLC. This guide covers everything you need to get productive.

Account Setup

First Login

  1. Navigate to your Isurus instance and click Sign in.
  2. Log in with your credentials or use a configured SSO provider (Google, Microsoft, Okta, Keycloak, or SAML) if your administrator has enabled one.
  3. After your first login, visit Settings to configure your profile.

Profile Settings

Click your username in the top-right menu and select Settings. Your settings page uses a sidebar layout with the following sections:

Profile Settings

Profile — Set your display name (shown on commits, issues, and pull requests) and update your email address.

Appearance — Choose a color theme and set your timezone.

Theme Selector

Isurus offers 26 color themes. The Site Default option follows whatever theme your administrator has configured, so your interface stays consistent with the rest of the instance unless you override it. Your timezone controls how dates and times are displayed throughout the application, including scheduled release publication.

Security — Change your password (local accounts only), manage SSH keys, and create API tokens.

If you've forgotten your password, click Forgot your password? on the sign-in page (or go to /forgot-password directly). Enter your email address and Isurus sends a reset link valid for 72 hours. The reset flow works only for local accounts — SSO-provisioned users recover through their identity provider.

Licensing

Isurus requires a valid license to operate. Your administrator configures the license during initial setup. If you see an "Unlicensed" page, contact your administrator. Resource limits (repositories, users, storage, CI minutes) are determined by your organization's license plan.

Organizations

Organizations group repositories and team members together.

Creating an Organization

  1. Click + New in the navigation bar and select New Organization.
  2. Enter an organization name (lowercase, letters, numbers, and hyphens only).
  3. Optionally add a description.
  4. Click Create Organization.

Organization Page

Organization Roles

Role Permissions
Owner Full access: manage members, settings, and all repositories
Member Read/write access to organization repositories

Managing Members

Organization Members

  1. Navigate to your organization page.
  2. Click Members in the sidebar.
  3. Use Add Member to invite users by username.
  4. Owners can remove members or change roles.

Repositories

Creating a Repository

New Repository Form

  1. Navigate to the organization where you want to create the repository.
  2. Click New Repository.
  3. Enter a name (lowercase, letters, numbers, hyphens, and dots).
  4. Add an optional description.
  5. Choose Public (visible to everyone) or Private (visible to org members only).
  6. Click Create Repository.

Browsing a Repository

Repository View

The repository page shows the README by default with a collapsible file tree on the left. The right sidebar displays metadata about the repository including Languages, Topics, License, and recent Activity.

Use the file search to quickly locate files by name, or browse the tree view to explore the directory structure.

Repository Settings

Repository owners can access settings via the Settings tab. Settings are organized in a sidebar with the following groups:

Repository Settings

  • General — Update the description, toggle visibility between public and private, and access the danger zone (delete repository).
  • Issues > Labels — Manage repository-level issue labels.
  • Issues > Templates — Create templates for bug reports, features, and more.
  • CI/CD > Secrets — Manage pipeline secrets for CI builds.
  • Integration > Webhooks — Configure event notifications for external services.
  • Integration > Tokens — Create repo-scoped API tokens.

Exploring Repositories

Explore Page

The Explore page lets you discover public repositories across the instance. Use the Language and Topic filter dropdowns to narrow results by programming language or subject area.

SSH Keys

SSH keys provide secure, password-free authentication for pushing and pulling.

Generating an ED25519 Key

ssh-keygen -t ed25519 -C "your@email.com"

When prompted, accept the default file location (~/.ssh/id_ed25519) and optionally set a passphrase.

Adding Your Key to Isurus

SSH Keys

  1. Copy your public key: 
    cat ~/.ssh/id_ed25519.pub
  2. Go to Settings and click SSH Keys under the Security section in the sidebar.
  3. Paste the key into the Key field.
  4. Give it a descriptive name (e.g., "Work Laptop").
  5. Click Add SSH Key.

Testing Your Connection

ssh -T your-isurus-host

You should see a message confirming successful authentication.

Cloning Repositories

HTTP Clone

hg clone https://your-isurus-instance/org/repo

You will be prompted for your username and password (or API token).

SSH Clone

hg clone ssh://your-isurus-instance/org/repo

Requires an SSH key added to your account.

Which Method to Choose?

Method Pros Cons
SSH No password prompts, secure Requires SSH key setup
HTTP Works everywhere, simple setup Requires credential storage or repeated entry

What's Next?

Now that you're set up, explore these guides:

×