Linking to a file

A test report, a build dashboard or a review tool often knows exactly which file and line it means. FEATit gives it one address to link to. The file opens in FEATit’s document viewer at that commit, with the line marked and in view, for anyone who can read the work area. The file is read from the reader’s own machine, so its contents never pass through the server.

The address

When your tool knows only the git repository, link to:

https://featit.com/-/open/file?remote=git@gitlab.com:acme/shop.git&path=src/cart/total.ts&at=4b825dc642cb6eb9a060e54bf8d69288fbee4904&line=42-48

FEATit finds the work area that holds that repository for the person who opens the link, and opens the file there:

https://featit.com/acme/shop/-/files/src/cart/total.ts?at=4b825dc642cb6eb9a060e54bf8d69288fbee4904&line=42-48

That second form is the file’s own address in the work area. Use it directly when your tool already knows the work area. On your own deployment, use its address in place of featit.com.

Parameter	What it is	Required
remote	The repository, as git remote get-url origin prints it, or host/path such as gitlab.com/acme/shop	Yes
path	The file, relative to the repository root	Yes
at	The commit, as a full 40- or 64-character id. Without it, the default branch is read	No
line	One line, 42, or a range, 42-48. Lines count from 1	No

The ssh and https spellings of a remote are the same repository: git@gitlab.com:acme/shop.git, ssh://git@gitlab.com:22/acme/shop and https://gitlab.com/acme/shop all match. A user name or token in a remote is ignored and never stored. Percent-encode a value with spaces or other special characters in it.

Building it in a script

remote=$(git remote get-url origin)
commit=$(git rev-parse HEAD)
open "https://featit.com/-/open/file?remote=$remote&path=src/cart/total.ts&at=$commit&line=42"

Use xdg-open on Linux or start on Windows. A dashboard opens the address in a new tab. If your remote carries a token, as some CI checkouts do, pass host/path instead, so the token is not in the link.

What the reader sees

• One work area holds the repository: the file opens at the commit with the line marked, scrolled into view and focused. A Markdown file opens in its source view, where lines are numbered.
• Several work areas hold it: the reader picks one. Comments and reviews on the file stay in the work area it is opened in.
• None of the reader’s work areas holds it: the page says so and what to do next. It looks the same whether no work area holds the repository or only ones the reader cannot open.
• A parameter is wrong: the page names the parameter and says why. A branch name or a short commit id in at is refused, never opened at the branch tip.
• Not signed in: the reader signs in and comes back to the same address.

A work area holds a repository when its settings name it: the repository its commit tracking checks against, or its clone address under Settings → Work area → Repository.

Who can open it

Anyone who can read the work area’s items. The file is read from that person’s own machine through the FEATit bridge or the desktop app, so the machine needs the repository and the commit. If it has neither, or is offline, the page says which.

The API

The lookup is also an API call, for a tool that wants the work area’s address itself. Authenticate with a bearer token: your session, your bridge’s credential or an agent key. Each sees only the work areas it can read.

curl -H "Authorization: Bearer $FEATIT_TOKEN" \
  "https://featit.com/api/repository-files/open?remote=git@gitlab.com:acme/shop.git&path=src/cart/total.ts&at=4b825dc642cb6eb9a060e54bf8d69288fbee4904&line=42-48"

GET /api/repository-files/open takes the parameters of the address and answers the work areas that hold the repository, each with the file’s address in it:

{
  "repository": "gitlab.com/acme/shop",
  "workAreas": [
    {
      "id": "6f0b6a52-7c1e-4d0e-9a51-2f7f0c1e9b3d",
      "name": "Shop",
      "reference": "acme/shop",
      "address": "/acme/shop/-/files/src/cart/total.ts?at=4b825dc642cb6eb9a060e54bf8d69288fbee4904&line=42-48"
    }
  ]
}

An empty workAreas means none. address is relative to the deployment you asked. A wrong parameter is answered 400 with the parameter and the reason:

{
  "reason": "malformed",
  "parameter": "at",
  "problem": "at-malformed",
  "message": "at must be a full commit id of 40 or 64 hexadecimal characters, not a branch name or a short id."
}