Data and privacy

ferryGL is often used in private repositories that belong to a client, whose contents may be covered by an agreement. This page lists what ferryGL reads, what it writes to Linear, and what it keeps, so you can check them against that agreement.

Credentials

• ferryGL uses your GitHub token and Linear API key only to call api.github.com and api.linear.app. It sends them nowhere else, and doesn't save them.
• It only sends read queries to GitHub, so a token with read-only access is enough. Prefer one.
• The Linear API key acts as you. ferryGL only changes Linear issues assigned to you.

What it reads from GitHub

For each issue and pull request in scope: the repository, number, title, URL, state (open, closed, merged, draft), the reason an issue was closed, and the description. For pull requests, also the author's login and the issues GitHub says it will close.

For the commit scan (prs_with_commits), ferryGL reads these same fields for every pull request in the route that you didn't open (updated since since), plus the logins of the authors of its first 100 commits. It then drops the pull requests without a commit of yours.

ferryGL reads descriptions to find the issues a pull request refers to, even when it doesn't copy them.

What it reads from Linear

• Your user ID and name, and each route's team, workflow states, project and label.
• For each GitHub URL, up to 20 links to it anywhere in the workspace, with the issue each is on: its identifier, title, status, team and assignee. That includes teammates' issues, which ferryGL never changes.
• When an item has no Linear issue of yours yet, your issues in the route's team, open or closed, with their identifier, title, status, description and link URLs. ferryGL uses them only to find one to adopt.

What it writes to Linear

For each Linear issue it creates:

On existing Linear issues, ferryGL only changes the status, adds links, and writes its metadata on the GitHub links it uses, including ones you added yourself. It keeps their title and subtitle. It never edits titles or descriptions, and never deletes anything.

Comments

With [sync] comment = true (off by default), ferryGL also posts a comment on the Linear issue for each change it makes, starting with (BY-FGL). The comment names the GitHub items (owner/repo#number), their GitHub state and the Linear status, and nothing else: no titles, descriptions or names. ferryGL never edits or deletes its comments.

Link metadata

ferryGL keeps its state in the metadata of the GitHub link on each Linear issue it manages, under keys that start with ferrygl_. The link of a pull request that rides with an issue gets only ferrygl_v, ferrygl_kind and ferrygl_linked_to.

When ferryGL updates a link, it replaces only its own keys and keeps any others.

What it never copies

• GitHub comments and reviews.
• GitHub labels, milestones and other fields.
• Other people's names or logins, including the authors of pull requests and commits.
• Code, commits and diffs.

If you turn on [copy] description, the GitHub description is copied as written, including any names, links or details in it.

Keeping more out of Linear

Titles are copied by default. If titles shouldn't leave GitHub, use templates without {title}:

[titles]
issue = "{repo}#{number}"
pr = "{repo}#{number}"
involved = "[PR] {repo}#{number}"

The templates apply to every route. The repository name and number still appear in each link and its URL.

Check that copying titles into your Linear workspace is acceptable for each repository you configure.

What it keeps on your machine

Nothing. ferryGL has no database, cache or log file of its own: everything it needs to remember is in the Linear links. Its output goes to the terminal, or wherever you redirect it. The output names GitHub items and the titles of the Linear issues it would create, so a log file you keep, as in the cron example, holds them too.