FerryDocs
GuidesConnect GitHub or GitLab

Connect with the API

A script connects an account with an access token, then lists repositories and branches.

Edit on GitHub
Connect an account with a token
curl -s -X POST http://127.0.0.1:7878/api/v1/git/connections \
  -H "Authorization: Bearer $FERRY_TOKEN" -H 'Content-Type: application/json' \
  -d '{"provider": "github", "token": "<access token>"}'

The uses the git endpoints of the API. A script uses an , because no person is there to click on the page of the provider.

Response
{
  "id": "git-4db07471b4a74da2a889",
  "provider": "github",
  "base_url": "https://github.com",
  "auth": "token",
  "status": "connected",
  "account": "you",
  "account_name": "Your Name",
  "token_hint": "…a1b2",
  "scopes": ["repo"],
  "token_expires_at": "2027-01-01T00:00:00Z",
  "client_id": null,
  "app_slug": null,
  "app_url": null,
  "manage_url": null,
  "repository_selection": null,
  "services": [],
  "created_at": "2026-10-01T09:45:04.121655Z",
  "updated_at": "2026-10-01T09:45:04.121655Z"
}

List, then create a service

List its repositories, the branches of one, then create a service
curl -s -H "Authorization: Bearer $FERRY_TOKEN" \
  http://127.0.0.1:7878/api/v1/git/connections/git-4db07471b4a74da2a889/repositories

curl -s -G -H "Authorization: Bearer $FERRY_TOKEN" \
  http://127.0.0.1:7878/api/v1/git/branches \
  --data-urlencode 'repo_url=https://github.com/you/api.git'
# {"default_branch":"main","branches":["main","develop"],"connection_id":"git-4db07471b4a74da2a889"}

curl -s -X POST http://127.0.0.1:7878/api/v1/services \
  -H "Authorization: Bearer $FERRY_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "api", "repo_url": "https://github.com/you/api.git", "branch": "main"}'

The service names no connection. Its repo_url is on github.com. Thus Ferry it with the account that you connected there.

ferry create --repo … and blueprints work the same way.

What Ferry stores

Ferry keeps the secrets of a connection in its database and asks for read access only.

Problems when you connect

Each error of an authorization has a cause and a fix.

On this page

List, then create a service