Skip to main content

What gets indexed

You pick any combination of three content types:
  • Pull requests: the title and description of every pull request, open and closed. Hymalaia also stores the author, assignees, labels, state, merge status, commit and changed-file counts, and timestamps as metadata.
  • Issues: the title and description of every issue, open and closed, with the author, assignees, labels, state, and timestamps as metadata.
  • Documents: documentation files from each repository. That means .md, .mdx, .markdown, .rst, and .txt files, plus extensionless files that are docs by convention, such as README, LICENSE, CHANGELOG, CONTRIBUTING, and CODEOWNERS.

What is not indexed

  • Comments on issues and pull requests, review comments, diffs, and commits
  • Source code, and data or config files such as .json, .yaml, and .csv
  • Files larger than 1 MB, binary files, and anything under .git, node_modules, vendor, dist, build, .venv, or __pycache__
  • Wikis, discussions, releases, and projects

Before you begin

You need:
  • An Hymalaia administrator account.
  • A GitHub personal access token, either fine-grained or classic. Hymalaia authenticates only with a token; GitHub App and OAuth sign-in are not supported.
  • For permission sync, the Hymalaia Enterprise Edition.

Create the token

Create the token as a user who can see every repository you want indexed; for permission sync, the token’s user also needs push access to every private repository. Fine-grained tokens are the least-privilege choice. Use a classic token when your organization does not allow fine-grained tokens, or when one token must cover repositories of several owners. Pick the expiration deliberately: when the token expires or is revoked, indexing stops until you save a new one in Hymalaia. After generating the token, copy it right away - GitHub shows it only once.
In GitHub, open Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens and select Generate new token (GitHub’s guide).
  • Resource owner: the user or organization that owns the repositories. Permission sync needs an organization permission, so for permission sync pick the organization, not your personal account. An organization must allow fine-grained tokens, and may require an approval step, before a token for it works.
  • Repository access: the repositories to index, or All repositories.
  • Repository permissions: set Contents, Issues, and Pull requests to Read-only. GitHub adds Metadata on its own.
  • Organization permissions, only if you use permission sync: set Members to Read-only.
Grant Contents even if you skip document indexing: when you name specific repositories, Hymalaia reads each repository root at setup, and a token without Contents fails validation.

Configure the connector in Hymalaia

1

Open the GitHub connector

In Hymalaia, go to Admin Panel -> Add Connector and select GitHub.
2

Create a credential

Select Create New and paste the token into GitHub Access Token.Leave GitHub Enterprise Server URL blank for github.com. To index a GitHub Enterprise Server instance instead, see GitHub Enterprise Server.
3

Name the connector and the owner

Enter a Connector Name, then the Repository Owner: the user or organization login that owns the repositories. For https://github.com/my-organization/my-repository, that is my-organization.
4

Choose the repositories

Under What should we index from GitHub?, pick one:
  • Specific Repository: enter one repository name in Repository Name(s), such as hymalaia, or several separated by commas, such as hymalaia,docs. Wildcards do not work.
  • Everything: index every repository of that owner the token can see.
With several repository names, Hymalaia only verifies at setup that one of them is accessible. A misspelled or inaccessible name is skipped during indexing without any error in the UI, so check each name.
When the owner is a personal account rather than an organization, Everything finds only that account’s public repositories. Use Specific Repository to index a personal account’s private repositories.
5

Choose the content types

Turn on at least one of Include pull requests?, Include Issues?, and Include Documents?. See What gets indexed for what each includes.
6

Choose the access type

Public shows every indexed document to all Hymalaia users. Private limits them to selected Hymalaia user groups. Auto Sync Permissions mirrors each searcher’s own GitHub access; see Permission sync.On tiers without permission sync this selector does not appear, and the connector is Public. See Document Access Controls for details.
7

Set the branch (optional)

Under Advanced Options, Branch sets the branch documents are read from, such as gh-pages; blank means each repository’s default branch. It only affects indexing when Include Documents? is on, though with a single repository Hymalaia still checks at setup that the branch exists. After changing it on an existing connector, select Re-Index on the connector’s page to pick up the new branch.
8

Create and verify

Select Create Connector. Hymalaia checks the credential and repositories, then starts indexing.Open Admin Panel -> Existing Connectors, select the connector, and check that the first indexing attempt reaches Succeeded. Then search Hymalaia for the title of a pull request or README you know is indexed.

GitHub Enterprise Server

To index a GitHub Enterprise Server instance, set GitHub Enterprise Server URL on the credential to your server’s address. Both the web host, https://github.example.com, and the API root, https://github.example.com/api/v3, work. Create the personal access token on the Enterprise Server instance itself, under the same Settings path; whether fine-grained tokens are available there depends on the server’s version and configuration. The URL must use HTTPS. At the default SSRF protection level, Hymalaia also rejects private-network addresses; an administrator can relax that level to reach an internal server. The URL lives on the credential, so one Hymalaia deployment can index github.com and an Enterprise Server side by side under different credentials. Self-hosted deployments can instead set the GITHUB_CONNECTOR_BASE_URL environment variable as a deployment-wide default for credentials that leave the field blank; see Configuration.

Permission sync

Set the access type to Auto Sync Permissions when you create the connector, and an Hymalaia user sees only the GitHub content they can read on GitHub. For an administrator the selector defaults to Public, so pick this option deliberately; the access type cannot be changed later in the admin UI, so switching means recreating the connector.
  • Documents from public repositories are visible to every Hymalaia user.
  • Documents from private repositories are visible to the repository’s collaborators, including people who have access through a team.
  • Documents from internal repositories (GitHub Enterprise) are visible to the organization’s members, matched by email as described below.

Matching GitHub users to Hymalaia users

Hymalaia matches by email: the public email on a user’s GitHub profile must equal their Hymalaia sign-in email, ignoring case. A user whose GitHub email is private, unset, or different from their Hymalaia email sees no private- or internal-repository content. To set a public email in GitHub, open Settings -> Emails, clear Keep my email addresses private, then pick the address under Public profile -> Public email.

Requirements for the token

  • The token’s user needs push access to every private repository the connector indexes, because GitHub only reveals a repository’s collaborator list to users with push access.
  • If any repository in the connector cannot be synced, the permission update run stops and the remaining repositories are skipped. Permission sync fails closed: while runs keep failing, users can lose access to private- and internal-repository documents, so fix a failing sync promptly.
  • For internal repositories, the token’s user must be a member of the organization. A non-member gets only the organization’s public members, which silently leaves out most users.
  • GitHub teams are not synced as Hymalaia groups. Team members still get access to private repositories through the collaborator list.
Permission sync is a paid feature, available in the Enterprise Edition. Without it, the access type selector does not appear, and connectors are Public.

Troubleshooting

The owner or a repository name is misspelled, or the token cannot see the repositories. For a fine-grained token, check that the repositories are selected under Repository access and that Contents read access is granted; Hymalaia reads the repository root during validation even when documents are not indexed.
The organization enforces SAML single sign-on. Authorize the token for the organization, then retry.
An Everything connector found nothing the token can see for that owner. Check the owner spelling, and give a classic token the repo scope or a fine-grained token access to the owner’s repositories.
The token cannot see them, so Hymalaia skips them without an error: a classic token is missing the repo scope, a fine-grained token does not include those repositories, or the owner is a personal account in Everything mode, which only finds public repositories.
The Branch value does not exist in the repository. Fix the branch name, or leave the field blank to use each repository’s default branch.
Their GitHub profile has no public email, or it differs from their Hymalaia sign-in email. See Matching GitHub users to Hymalaia users.
The token has used up GitHub’s hourly API quota, usually because something else shares it. During indexing Hymalaia waits out the limit and retries on its own; for this error during setup, wait for the quota to reset, then retry.
The token was revoked, expired, or pasted incorrectly. Create a new token and update the credential on the connector’s page under Admin Panel -> Existing Connectors.