Search

Overview

Type what you remember and get back everything you can read that matches it: work items, merge requests, comments, releases, repositories, groups, services, specification documents and wiki pages, ranked together in one list rather than nine lists you have to visit in turn. You never have to decide first whether the thing you are looking for was a work item or a merge request — that is the search's job, not yours.

You can point a search at everything you can see, at one group and everything beneath it, or at a single repository. Whichever you choose, a result only appears if you could already open it, so a search is a safe thing to run in a group you share with people who cannot see everything you can.

Before you start

How it works

One ranked list, not eight

Every kind of result is scored against your query and the scores are compared with each other, so the most relevant merge request can outrank the least relevant work item and land above it in the same list. Each hit carries a rank, which is the score that put it where it is; the list is ordered by that, and by id where two hits tie, so the same query gives the same order twice.

A hit is a signpost, not a copy of the thing it points at. You get its kind, its id, a title, a short excerpt and when it last changed, plus the scope it sits in and its number for the kinds that have them — enough to render a row and follow the link. A hit with nothing to excerpt, a repository with no description say, arrives without one. Everything else lives at the resource's own address.

A comment's scope and number are those of the work item or merge request it was written on, and its on says which of the two it is, so every comment leads back to its thread. A service's scope is the group it belongs to. A specification document carries its file's path in the repository, and a wiki page carries the page's current path, which is what reads it.

What each kind matches

Two different kinds of matching are at work in that table, and the difference is the thing people trip over. Titles, descriptions and bodies match whole words, with English stemming — deploying finds deployed and deploys, but deplo finds nothing. Paths, slugs and document ids also match fragments, because they are identifiers and no amount of stemming makes check find checkout-service. So a half-typed word finds a repository and does not find a work item.

Comments are searched as themselves rather than as part of the thing they are attached to, which is why a discussion that repeats a term ten times produces ten hits rather than one very relevant work item. Specification documents are matched on their title, summary and document id — not their full body.

Writing a query

The box takes the syntax a search box has trained you to expect:

Casing never matters. Punctuation is dropped from word matching, but it counts in a path, a slug or a document id — which is what makes platform/pay match the path it looks like. The operators shape word matching only: a fragment is compared against the whole of what you typed, so quoting a phrase or excluding a word does not change which repositories, groups or services a fragment finds.

A query of nothing but spaces is refused rather than treated as "everything", because a search that returns everything you can read is never what anybody meant. So is a query made only of very common words, in effect — the and and are dropped from word matching and leave nothing to match on.

Where the search runs

A scoped search returns the things filed inside the scope. Repositories and groups are containers rather than things filed in one, so a group or repository search never returns them — to find one, search across everything and narrow with types. A service belongs to a group, so a search in that group or one above it finds it, and a repository search does not.

Paging

A page holds up to 50 hits and defaults to 20. A full page comes back with a next_token; pass it on the next call to get the page after it, and keep going until a response arrives without one. That is the only reliable stopping condition — never stop because a page looked short, and never pass a cursor from a listing to a search or the other way round. A search cursor is a position in relevance order, a listing cursor is a position in most-recently-updated order, and the two mean different things.

How to

Search everything you can see

The broadest search: every group you can read, every kind of result, ranked together. It is the right starting point when you know the words but not where the thing lives.

Signed out, this call still works and answers with public results only. Signed in, it spans everything your memberships reach — which can be surprisingly wide, so scope the search when you already know where you are looking.

Search a group and everything below it

A group search covers the group, every subgroup underneath it and every repository in any of them. It is the search to use when a term means one thing in your team's group and something else across the company.

You need to be able to see the group. A private group you are not a member of answers 404 rather than telling you it exists, and answers 401 if you are not signed in at all.

Search one repository

The narrowest scope, and the fastest to read: everything filed against one repository, with no results from anywhere else competing for the top of the list.

Narrow a search to one kind of thing

types takes a comma-separated list of the kind names from the table above — issue, merge_request, repository, group, release, comment, service, spec. Leave it out and every kind is searched.

A name that is not on the list is refused with 400, rather than being ignored. Asking for ?types=issues and quietly getting merge requests back would be an answer about a search you did not run, so the refusal names every value that would have worked.

Write a query that finds one specific thing

When a plain query returns too much, the three operators in the table above cut it down fast, and they compose. "connection pool" -test finds the design discussion and drops the test that mentions it in passing. timeout or deadline widens a term whose spelling nobody agreed on.

A query may be up to 256 characters. If you are pasting a stack trace, quote the one distinctive line from it rather than the whole thing.

Page through a long result set

Ask for up to 50 hits at a time, then follow the cursor. Every response that fills its page carries next_token; a response without one is the end.

Asking for more than 50 is not an error — you get 50. Asking for a page size that is not a number is refused with 400.

Find a repository, group or service by name or path

These three kinds match on a fragment of their path or slug as well as on their description, which makes search a fast way to jump to somewhere you can half-remember the name of. platform/pay finds platform/payments-api, and check finds the checkout service.

Search these from the top-level scope. A group or repository search cannot return them.

Find a specification document

Indexed specification documents are searchable by title, summary and document id, so you can find the document that owns a decision without knowing which repository it was written in.

A document becomes searchable once it has been indexed on the repository's default branch. On any other branch the corpus is checked but not published, so a document that exists only on a working branch does not appear until the change lands — and a document deleted on the default branch stops appearing once that change is indexed.

Reference

Limits

Searching creates nothing, so it consumes none of your namespace's creation limits, and the size of a result page is the only bound on what one call returns. Nothing here differs by plan.

Troubleshooting

FAQ

Related