GitHub Handle Validator

GitHub username validation: rules, redirects and platform tie-ins

A GitHub username identifies a user or organization account and appears in every URL on the platform: github.com/torvalds, username.github.io, profile READMEs at the special repo username/username, GitHub Sponsors links, GitHub Actions workflows, container registry paths. Validating a username matters in forms that pre-create profile links, in CI scripts that consume environment variables (GITHUB_ACTOR), and in social-link fields where a wrong username produces 404 instead of a profile.

The format rules are stricter than they look: 1 to 39 characters, alphanumeric plus single hyphens, no consecutive hyphens, cannot start or end with a hyphen. The case-insensitive routing means octocat and OCTOCAT resolve to the same account, but the canonical casing is preserved for display.

Format rules and the canonical regex

• Length: 1 to 39 characters.
• Allowed characters: [A-Za-z0-9-] — letters, digits and hyphen.
• Hyphen rules: cannot start or end with a hyphen; consecutive hyphens (--) are not allowed.
• Reserved words: admin, root, login, api, www and other system paths are blocked at signup.
• Case-insensitive: OctoCat, octocat and OCTOCAT all hit the same profile. Search and URLs normalize to lower case.

// Canonical GitHub username regex
const GITHUB_USERNAME = /^[a-z\d](?:[a-z\d]|-(?=[a-z\d])){0,38}$/i

function validateGithubUsername(name) {
  return GITHUB_USERNAME.test(name)
}

// Notable accounts
validateGithubUsername('torvalds')   // true (Linus Torvalds)
validateGithubUsername('gaearon')    // true (Dan Abramov)
validateGithubUsername('-bad')       // false (leading hyphen)
validateGithubUsername('a--b')       // false (consecutive hyphens)

Username-based features: Pages, Profile README, Sponsors

The username is woven into several GitHub features:

• GitHub Pages: username.github.io hosts a static site directly from the repo of the same name. Free tier with a 1 GB site limit and 100 GB/month bandwidth.
• Profile README: creating a public repo named exactly username/username displays its README at the top of the user's profile — used for portfolio cards, stats badges and pinned READMEs.
• GitHub Sponsors: revenue feature using the username as donation URL (github.com/sponsors/username). Available to individuals and organizations after eligibility check.
• GitHub Container Registry: container images live at ghcr.io/username/image:tag — the username is the namespace.
• GitHub Actions: GITHUB_ACTOR environment variable in every workflow carries the username that triggered the run.

Username changes, redirects and squatting

Unlike X/Twitter, GitHub auto-redirects renamed accounts: when you change your username, the old URL keeps working until the old name is reclaimed by someone else, and even then GitHub may keep historical redirects for repository URLs. Username changes are limited to roughly one per year via UI. Old repository clone URLs continue to work via redirect, which is critical for projects that already have downstream consumers. GitHub also actively combats username squatting: trademark holders can request reclamation of inactive accounts that violate trademark policy under the GitHub Acceptable Use Policy.

Organization vs user accounts and Enterprise

Organization names follow the same format constraints as user names: 1-39 chars, alphanumeric + single hyphens. Organizations cannot own subprofiles directly — every member has their own user account and joins the org as a collaborator. GitHub Enterprise Server (self-hosted) uses the same username constraints internally but maintains a separate namespace from github.com. The free tier of GitHub Actions grants 2,000 CI minutes/month for private repos on individual accounts (unlimited for public repos); organizations get a higher tier under paid plans. API rate limits: 5,000 requests/hour for authenticated users, 60/hour unauthenticated.

Brazilian dev community on GitHub

Major Brazilian organizations have a strong GitHub presence: rocketseat (online education), nubank (open-source fintech tooling), iFood, VTEX, PicPay, Stone. GitHub Actions adoption grew rapidly across Brazilian DevOps teams 2022-2025 as a free CI alternative. For users uncomfortable with GitHub's policies, GitLab and Codeberg (Forgejo) are common alternatives — both use looser username rules (typically 2-255 chars on GitLab).

FAQ

What is the maximum username length? 39 characters. The limit dates back to early GitHub and remains for backwards compatibility with URLs, DNS for Pages (which uses the username as a subdomain) and various API endpoints.

Can a username start with a hyphen? No. The first character must be alphanumeric. The trailing character also must be alphanumeric, and you cannot have consecutive hyphens anywhere in the name.

If I rename my account, do old URLs break? No — GitHub maintains auto-redirects from the old username, including repository URLs and clone endpoints. Renames are limited to about one per year, and the redirect remains until someone else claims the old name.

Are GitHub usernames case-sensitive? No, lookups are case-insensitive. github.com/torvalds and github.com/Torvalds both resolve to the same profile, with the canonical casing preserved for display.

Can I have underscores or periods in my username? No. Only letters, digits and single hyphens are allowed. This is stricter than Twitter (underscore) and Instagram (period + underscore).