OXYGENHUB

Working with Others

Andy McCall edited this page · 1 revision

Working with Others

Where a repository can live

flowchart TB
    Local[(Your repository)]
    Local <-->|HTTPS| Hub[(OxygenHub)]
    Local <-->|HTTPS| Serve[(oxy serve on your server)]
    Local <-->|direct| Bucket[(Your S3, GCS or Azure bucket)]
    Local <-->|direct| Dir[(A shared directory)]
    Local <-->|oxy git fetch / push| Git[(A Git remote)]

All of these are remotes. The commands are the same whichever you use: oxy clone, oxy fetch, oxy pull, oxy push.

Signing in to a hub

oxy auth login https://oxygenhub.io      # shows a code to approve in the browser
oxy auth status                          # hubs you are signed in to
oxy auth logout https://oxygenhub.io

One token per hub covers every repository on it. It is kept in ~/.config/oxy/credentials.toml, readable by you only, or in the system keyring if you name a credential helper. Nothing secret is written into a checkout.

Fetch, pull and push

sequenceDiagram
    participant You as Your repository
    participant Remote
    You->>Remote: oxy fetch
    Remote-->>You: new changes, signed bookmark positions
    Note over You: origin/main moves,<br/>your main does not
    You->>You: oxy pull = fetch, then union into your bookmarks
    You->>Remote: oxy push (old state, new state, signature)
    alt the remote's bookmark is still at your old state
        Remote-->>You: accepted
    else someone pushed first
        Remote-->>You: refused: pull, then push again
    end
  • oxy fetch updates origin/main without touching your bookmark.
  • oxy pull fetches, then makes each local bookmark the union of both sides. Unrelated changes simply sit side by side.
  • oxy push moves the remote bookmark by compare-and-swap: it is refused if the remote moved since you last fetched.

Running your own server

oxy serve --root /srv/oxy --bind 0.0.0.0:8890 --token SECRET \
          --tls-cert cert.pem --tls-key key.pem
echo SECRET | oxy auth login https://host:8890 --with-token
oxy clone https://host:8890/project

Reads stay open; pushes need the token. Without TLS options the server speaks plain HTTP, which belongs on a loopback address or behind a TLS terminator.

Deciding who may publish

A trust policy in the repository names who may move each bookmark. Servers and clients both enforce it. See Trust Policy.