DirectAdmin Git API: creating repositories, deploys and webhooks

Since version 1.6x DirectAdmin has a Git feature (under Git in Evolution). We couldn't find API documentation for it. For Invoker Link we read the calls from the Evolution interface itself and tested them on DirectAdmin 1.710. This article is for developers and administrators.

Endpoints

All calls run as the user (for example with a login key) and speak JSON.

Creating

curl -X POST -H "Content-Type: application/json" \
  "$DA/api/git/domain/example.com" \
  -d '{"name":"website","remote":"git@github.com:company/website.git","keyfile":".ssh/deploy-website"}'

The response includes uuid, branches (already fetched), webhook_url and valid.

Pitfall: the keyfile path must be relative to the home directory. An absolute path returns:

{"message":"invalid create parameters: keyfile: must be relative","type":"BAD_REQUEST"}

Configuring and running a deploy

curl -X PUT -H "Content-Type: application/json" "$DA/api/git/uuid/$UUID" \
  -d '{"deploy_branch":"main","deploy_dir":"domains/example.com/public_html","keyfile":".ssh/deploy-website"}'
curl -X POST -H "Content-Type: application/json" "$DA/api/git/uuid/$UUID/deploy" -d '{}'

deploy_dir is relative to the home directory too. Both calls return 204 with no body.

How do deploys and webhooks behave?

What we observed:

• Mirror: DirectAdmin creates a bare mirror in ~/domains/{domain}/{name}.git and fetches all branches.
• A deploy is an export: the branch's files land in the deploy directory, without a .git folder.
• Existing files stay: a file that isn't in the repository is not deleted. Files with the same name are overwritten.
• Webhook = fetch + deploy: a POST to webhook_url fetches and deploys in one go. A file we deleted from the deploy directory was back after the webhook.
• The webhook URL has no extra authentication: the long uuid in it is the only protection.

Pitfall: subdomains

The Git API only works on main domains. For a subdomain you get:

{"type":"NOT_FOUND"}

So create the repository under the main domain and set deploy_dir to the subdomain's folder. Newer DirectAdmin versions give a subdomain its own folder, for example domains/status.example.com/public_html.

Deploy keys

GitHub only allows a deploy key on one repository. Create a separate key per repository:

ssh-keygen -t ed25519 -N "" -C "deploy website" -f ~/.ssh/deploy-website

Test whether GitHub accepts it before creating the repository:

GIT_SSH_COMMAND="ssh -i ~/.ssh/deploy-website -o IdentitiesOnly=yes" git ls-remote git@github.com:company/website.git