Guides

Keep your repository map up to date

Optional. If your API's code is in a GitHub repository, a GitHub Action can keep the map Tether has of it current: on every push to your default branch, your own runner analyses the checkout and publishes what changed. Your source code never leaves the runner, and the key it uses cannot change your live assistant.

Nothing else in Tether needs this. It repeats, on every push, the optional repository step of Connect your platform.

What it does

On your runner, the action:

installs the tether CLI on Node 22 and runs tether analyze, which reads your checkout and writes .tether/knowledge/ and a local index, on the runner;
runs tether publish as a dry run with the secret scan, and prints the plan in the job summary. If the scan finds a secret, the step fails and nothing is sent;
runs tether publish --send with your workspace's CI key.

What reaches Tether is three kinds of artifact, each tagged with the commit:

What	Where it goes	What happens
Your OpenAPI contract	The import's draft step	Tether records the draft. Nothing is imported until a person declares whether each operation reads or writes
Docs you choose	Knowledge	Stored with their `source`. One you already hold is replaced only if the key was issued to replace
Domain vocabulary	A suggestion	Waits in the dashboard. Your pack changes only when you accept it

Your source code, your routes, the dependency graph, the file list and the index are never sent, and the action uploads nothing as an artifact. The CI key cannot reach any other route: changing the pack, policy, catalog, endpoint, users or keys is refused with a reason.

Set it up from the dashboard

Open the dashboard's Repository section (it is also on the last step of setup):

Issue a CI key. It is shown once. Tick "May replace documents" only if you want the runner to update documents you already hold.
Add the workflow. Type your GitHub owner, repository and default branch. The panel shows the workflow, and Create the workflow on GitHub opens GitHub's new-file page for .github/workflows/tether.yml with it filled in; commit it. Add the TETHER_CI_KEY secret opens your repository's Actions secrets: name it TETHER_CI_KEY and paste the key. The key is never put in a link or in the file.
See what arrived. After a run, the panel shows the last publish (its commit, when, with which key, and each artifact) and the vocabulary waiting for you, with Accept and Dismiss.

The workflow

name: Tether repository map

on:
  push:
    branches: ['main']
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: tether-publish
  cancel-in-progress: false

jobs:
  publish:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - uses: SynapseGeorgia/Tether/actions/publish@v0.1.0
        with:
          tether-url: 'https://your-tether-host'
          ci-key: ${{ secrets.TETHER_CI_KEY }}
          api-url: 'https://api.example.com'

Input	What it is
`tether-url`	The Tether API your workspace is on (required)
`ci-key`	The CI key, from `secrets.TETHER_CI_KEY` (required). A secret key, `tth_`, is refused
`api-url`	Where your operations are called (`--api`), when your OpenAPI document names no absolute server
`directory`	What to analyse, relative to the checkout (default `.`)
`docs`	Globs over the docs the analysis lists, one per line (default: every doc)
`replace`	`'true'` to replace documents already held; refused unless the key allows it
`allow-secret`	Fingerprints of reviewed secret-scan false positives, one per line
`cli`	A published tarball URL or npm package spec to install the CLI from

The workflow needs only contents: read, and persist-credentials: false keeps the checkout's token off the disk, since nothing here pushes.

A GitHub App

None is needed: the link above opens GitHub with the file filled in, and you add the secret yourself, so the key stays among your repository's secrets. An App that installs the workflow for you is designed but not registered. It would need metadata read, contents read only to see whether the workflow is already there, and, to open the setup pull request, workflows, contents and pull requests write. It would never need to read your code, and Tether never does.

Repository: the CI key, what arrived, suggestions
The tether CLI: tether publish with a CI key
Connect your platform