Git connections

Starts connecting an account on the provider's own pages and answers with where to send the browser (status: redirect): a URL to navigate to (method: get) or to submit a form with fields to (method: post). When the provider is done it sends the browser back to redirect_uri (the dashboard's /git/callback page) with query parameters to hand to POST /api/v1/git/callback.

GitHub: the browser posts a manifest to GitHub, which registers a private GitHub App for this server (on the user's account, or in organization) and then asks the account which repositories the app may read. No token is ever typed: the app's key mints short-lived tokens.

GitLab: the account authorizes an OAuth application created for this server (scopes read_api and read_repository, redirect URI = redirect_uri). Give its client_id and client_secret the first time (400 git_application_required otherwise); they are kept for later authorizations.

With connection_id, resumes a pending connection or authorizes a connection again; the answer is status: connected when nothing is left to do (a GitHub App that is already installed).

Response BodyCopy Anchor Link

Takes the query parameters the provider sent the browser back with (to the redirect_uri given to POST /api/v1/git/authorize): state, and code and / or installation_id. Answers with the next page to send the browser to (status: redirect: after GitHub registered the app, its installation page) or with the connection (status: connected). A state works once, for an hour. Without state but with an installation_id (GitHub sends the browser back after an installation was changed on its own pages), the connection of that installation is read again.

Response BodyCopy Anchor Link

The GitHub / GitLab accounts this server is authorized to read the repositories of, with the names of the services whose repository each one clones. A pending connection was started in the browser and not finished. Secrets are never returned.

Response BodyCopy Anchor Link

The alternative to authorizing in the browser (POST /api/v1/git/authorize), for scripts and for instances where no application can be registered: connects the account a personal access token belongs to. Ferry asks the provider who the token is, then stores it. On GitHub use a classic personal access token with the repo scope, or a fine-grained one with read access to Contents and Metadata; on GitLab one with the read_api and read_repository scopes. base_url selects a self-hosted instance (GitHub Enterprise Server, GitLab self-managed). An account that is already connected gets the token instead of what it had (200 instead of 201). The token is never returned by the API.

Response BodyCopy Anchor Link

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

Deletes the connection and its secrets. What it authorized stays on the provider until it is removed there: the GitHub App (delete it in GitHub's settings), the OAuth grant or the token. Refused while services' repositories are cloned with it, unless force=true: those services keep their repository and are cloned without credentials from then on, which fails for private repositories.

Path ParametersCopy Anchor Link

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link

The repositories the connection can read, asked from the provider on every call, most recently updated first: for a GitHub App the repositories the account allowed it to read (see manage_url); otherwise the account's own, its organizations' / groups' and those it collaborates on. At most 1000 are listed (truncated says when there are more). Use a repository's clone_url as the repo_url of a service: it is cloned with this connection.

Path ParametersCopy Anchor Link

Response BodyCopy Anchor Link

The branches of a repository and its default one, asked from the repository's remote itself (git ls-remote) on every call. Works for any repository URL a service can deploy from; it is read the way a deploy would clone it: with the git connection that serves the URL when there is one (connection_id in the answer), with the credentials the URL carries, or without any.

Query ParametersCopy Anchor Link

Response BodyCopy Anchor Link