GitHub & Registry Integrations | ZopDev Developer Docs

Integrations are the external systems ZopNight reaches into when you deploy. The most important one today is GitHub: ZopNight authenticates as a GitHub App, lists your repos, kicks off Actions-based builds, and receives push webhooks. Container registries are managed as integrations too: ECR, GAR and ACR through your connected cloud account (no secret is stored; access is minted at request time), and Docker Hub, GitHub Container Registry and GitLab Container Registry through credentials.

GitHub App Installation

The user clicks “Connect GitHub” in ZopNight.
ZopNight redirects to GitHub’s app install page via GET /integrations/github/install.
GitHub redirects back with an installation ID, which lands on GET /integrations/github/callback.
ZopNight stores the installation, exchanges short-lived tokens at deploy time, and starts receiving webhooks.

Read vs write App

ZopNight runs two GitHub Apps with different permission sets, selected by an optional role query param on the install call:

role=read (default). A read-only App (repository contents + metadata read). Enough to list repos and dispatch builds. This is what deploy-focused flows install.
role=write: a write-capable App (contents, workflows, secrets, variables, pull requests write). Required for IaC-governance CI auto-wiring, which commits the workflow file and repo secret. The ZopNight settings card installs this App.

An org typically holds one installation per App, though a separate row is created per GitHub account the App is installed on (a personal account and an org, say). Each github_app integration records which App it belongs to, and the list endpoint returns a role field so a client can show the right one.

GET /integrations/github/install

Initiates the GitHub App install flow. Returns a redirect to the GitHub App install page. Optional ?role=read|write selects which App to install (defaults to read).

GET /integrations/github/callback

OAuth/install callback. ZopNight finalizes the installation and stores the integration record.

Manage Integrations

GET /integrations

List integrations.

{
  "data": [
    {
      "id": "7e6d5c4b-3a2f-4e1d-8c0b-9a8f7e6d5c4b",
      "orgId": "3f6c2a9e-8b1d-4c7e-9f2a-1d5e6b7c8a90",
      "name": "Acme GitHub Org",
      "provider": "github_app",
      "category": "git",
      "config": "{...}",
      "status": "active",
      "role": "read",
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-04-01T10:00:00Z"
    },
    {
      "id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
      "orgId": "3f6c2a9e-8b1d-4c7e-9f2a-1d5e6b7c8a90",
      "name": "ECR production AWS",
      "provider": "aws_ecr",
      "category": "registry",
      "config": "{...}",
      "status": "active",
      "createdAt": "2026-04-02T08:00:00Z",
      "updatedAt": "2026-04-02T08:00:00Z"
    }
  ]
}

config is a JSON string whose contents depend on the provider. role is set only on github_app integrations (read or write).

POST /integrations

Create an integration. Most flows go through the connect endpoints (GitHub install, GCP OAuth); this is the manual path for static credentials (e.g. Docker Hub username/password).

curl -X POST https://api.zop.dev/integrations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Docker Hub acme",
    "provider": "dockerhub",
    "category": "registry",
    "credential": "{\"username\":\"acme-bot\",\"password\":\"...\"}"
  }'

The body takes name, provider, category, an optional config (a JSON string) and credential (a JSON string, for example {"username":"...","password":"..."} or {"token":"..."}). For ECR, GAR and ACR the credential names the cloud account to use: {"cloudAccountId":"..."}.

GET /integrations/{id}

Get an integration by ID. Secrets are never returned.

PUT /integrations/{id}

Update an integration's name, config, or credential.

DELETE /integrations/{id}

Delete an integration. Deployments referencing it will fail until reassigned. GitHub integrations also revoke the installation on GitHub's side.

Supported Providers

Category	`provider` values	Used for	Auth
`git`	`github_app`, `github`, `gitlab`, `bitbucket`	Source code, build dispatch, webhooks	GitHub App installation token (short-lived), or a token for the other providers
`registry`	`aws_ecr`, `gcp_gar`, `azure_acr`	Container image push/pull on AWS, GCP, Azure	The bound cloud account
`registry`	`dockerhub`, `github_registry`, `gitlab_registry`	Container image push/pull	Username + password, or access token
`itsm`	`jira`	Ticketing	Jira credentials
`ai_gateway`	`ai_gateway`, `openai`, `anthropic`, `openrouter`, `aws_bedrock`	AI gateway and model providers	Provider credentials
`observability`	`prometheus`, `mimir`, `victoriametrics`	Your own metrics backend	See Observability
`observability`	`loki`, `victorialogs`, `datadog`	Your own logs backend	See Logs backends
`observability`	`tempo`, `jaeger`, `zipkin`	Your own traces backend	See Traces backends

For the MCP integration (AI assistants connecting to ZopNight) see MCP Server.