Conexões e origens Git
Use estes endpoints para consultar capacidades Git, gerenciar conexões Forgejo e GitLab, conectar a conta pessoal do GitLab, selecionar um repositório e vincular uma origem a um projeto. As rotas ficam sob /v1 e usam a organização ativa.
Autenticação e permissões
Use o método de autenticação permitido para cada rota; com token de usuário, envie também x-organization-id (com API Key da organização, o header é dispensável). Respostas bem-sucedidas usam { "status": "success", "data": ... }. A credencial do provedor só pode ser criada, trocada ou revogada por uma sessão de owner; uma API Key não substitui essa sessão. A credencial não é devolvida nas respostas.
| Operação | Permissão mínima |
|---|---|
| Consultar provedores e runtimes | Autenticação válida na organização (sessão ou API key permitida pela rota) |
| Listar conexões, validar repositório ou consultar branches | project.source.update em project:* |
| Criar, trocar credencial ou revogar conexão | Sessão de owner da organização |
| Conectar, consultar ou desconectar o próprio GitLab | Sessão de usuário de owner ou de membro que pode criar projetos na organização ou em um time |
| Ler a origem e as branches do projeto | project.read em project:<project-id> |
| Alterar origem e build do projeto | project.source.update em project:<project-id> |
| Iniciar o build depois de alterar origem ou build | project.deploy.trigger em project:<project-id> |
| Criar projeto HTTP | project.create em organization:* |
Consultar capacidades e runtimes
GET /v1/git/providers
GET /v1/git/runtime-catalogGET /git/providers retorna api_version e uma lista com id, available e as capacidades repositoryDiscovery, pushDeploy, nativePreviews e versionDeploy. A disponibilidade indica se novos projetos desse provedor podem ser aceitos; as capacidades indicam operações oferecidas pela conexão. O catálogo atual inclui github, forgejo e gitlab. O item gitlab traz também oauth_available, que indica se a conexão pessoal por OAuth com o gitlab.com está disponível. O endpoint exige autenticação da organização e não exige project.read.
GET /git/runtime-catalog retorna os runtimes e versões Git disponíveis no catálogo atual, sem campos de imagem.
Gerenciar conexões Forgejo e GitLab
Listar conexões
GET /v1/git/connectionsRetorna somente conexões da organização ativa. Uma conexão é projetada publicamente assim:
{
"id": "connection-id",
"provider_id": "forgejo",
"instance_url": "https://forgejo.example.test",
"display_name": "Forgejo da equipe",
"status": "active",
"connection_revision": 1,
"capabilities": {
"repositoryDiscovery": false,
"pushDeploy": true,
"nativePreviews": false,
"versionDeploy": true
}
}created_at e updated_at podem aparecer como datas ISO. A resposta não inclui token, revisão da credencial, política de acesso ou dados privados de conectividade.
Uma conexão pessoal do GitLab, criada pelo fluxo OAuth descrito em Conectar a conta pessoal do GitLab, traz também owner_user_id, auth_method: "oauth", account_username e, quando o GitLab deixou de aceitar a autorização, needs_reauth: true. Ela aparece para a pessoa que a conectou e, só como registro de existência, para o owner da organização. Somente a própria pessoa pode usá-la para listar repositórios, resolver caminhos e vincular projetos; uma API Key não usa conexões pessoais. A capacidade repositoryDiscovery é true nas conexões pessoais e false nas conexões GitLab por token.
Criar conexão
POST /v1/git/connectionsO corpo exige os campos abaixo e retorna 201. Use uma URL HTTPS com certificado confiável e o caminho explícito do repositório; conexões por token não oferecem descoberta de repositórios. Uma instância privada precisa estar acessível pela conexão habilitada para a organização. Para publicações por evento, o Forgejo também precisa conseguir entregar hooks por HTTPS à Zenifra. Não use URL ou parâmetro de comando para transmitir o token.
| Campo | Tipo | Descrição |
|---|---|---|
provider_id | string | forgejo ou gitlab |
instance_url | string | Endereço HTTPS canônico da instância, como https://gitlab.com ou o endereço de um GitLab próprio (até 2048 caracteres) |
display_name | string | Nome de exibição escolhido pela organização (1 a 120 caracteres) |
repository_path | string | Caminho explícito, como equipe/aplicacao (3 a 1024 caracteres) |
username | string | Somente Forgejo: conta usada pela credencial (1 a 256 caracteres). Não envie em conexões GitLab |
token | string | Token usado na validação, até 8192 caracteres; nunca é retornado |
Informar uma URL não cria acesso a uma rede privada, e abrir o endereço no seu navegador não confirma que a Zenifra consegue alcançá-lo. Quando possível, limite o token ao repositório selecionado. Consulte escopos de token do Forgejo 15.0: read:repository atende à validação e às operações de leitura usadas pelo deploy manual; write:repository e permissão da conta para administrar hooks são necessários para publicações por branch, tag e release. A documentação de webhooks do Forgejo 15.0 descreve os hooks.
No GitLab, use um token pessoal, de grupo ou de projeto com os escopos api e read_repository. Para a Zenifra criar o webhook de publicação por push e de previews de merge requests, o token precisa do papel Maintainer no projeto. Caminhos com subgrupos, como grupo/subgrupo/aplicacao, são aceitos. Veja Deploy a partir do GitLab.
Atualizar credencial
PATCH /v1/git/connections/:connectionId/credentialsO corpo aceita repository_path, username e token; em conexões GitLab, username é ignorado. A credencial substituída não é exibida. Conexões pessoais do GitLab não aceitam esta rota e retornam 404 (GIT_CONNECTION_NOT_FOUND): a própria pessoa reconecta pelo fluxo OAuth. O servidor controla a revisão e aplica as verificações de autorização da sessão owner.
Revogar conexão
DELETE /v1/git/connections/:connectionIdQuando a revogação é aceita, o retorno contém connection com a projeção pública revogada e cleanup_pending. cleanup_pending: true informa que a limpeza associada ainda está pendente; não confirma que ela foi concluída na instância remota. Uma operação pendente pode impedir a revogação e retornar 409; nesse caso, a conexão continua ativa. Somente uma resposta de sucesso confirma que a autorização local foi revogada. Conexões pessoais do GitLab retornam 404 (GIT_CONNECTION_NOT_FOUND) nesta rota; a pessoa as remove com DELETE /v1/auth/gitlab/personal. A gestão da autorização GitHub existente continua nas rotas OAuth atuais.
Conectar a conta pessoal do GitLab
Cada pessoa pode conectar a própria conta do gitlab.com à organização ativa. As rotas abaixo exigem a sessão do usuário (token de usuário com x-organization-id); uma API Key não as usa. Podem conectar o owner e os membros que podem criar projetos na organização ou em um time.
GET /v1/auth/gitlab
GET /v1/auth/gitlab/status
DELETE /v1/auth/gitlab/personalGET /auth/gitlab retorna { authorization_url, state } e grava um cookie que vincula o navegador ao fluxo. Abra authorization_url no mesmo navegador: o GitLab pede os escopos api e read_repository e, depois da autorização, a Zenifra volta para a página Conta do Console com ?gitlab_connected=1 ou ?gitlab_error=<código>. Os códigos possíveis são access_denied, auth_failed, missing_code, invalid_state, permission_required e unavailable. Sem permissão para conectar, a rota retorna 403; quando a conexão com o GitLab não está disponível, retorna 503 (GIT_OAUTH_UNAVAILABLE).
GET /auth/gitlab/status retorna a conexão de quem chama na organização ativa:
{
"available": true,
"connected": true,
"connection_id": "connection-id",
"username": "usuario-gitlab",
"connected_at": "2026-11-11T12:00:00.000Z",
"needs_reauth": false
}Com needs_reauth: true, o GitLab deixou de aceitar a autorização (por exemplo, porque ela foi revogada no GitLab): builds dos projetos dessa conexão falham até a pessoa conectar de novo por GET /auth/gitlab.
DELETE /auth/gitlab/personal remove os webhooks que a Zenifra criou nos projetos do GitLab, revoga o acesso e retorna { "disconnected": true }, ou false quando não havia conexão. Os projetos criados com a conexão deixam de receber deploys; depois de reconectar, vincule o repositório de novo com PUT /v1/project/:id/source.
Resolver repositórios e branches
Resolva um repositório sem descoberta global usando seu caminho explícito:
POST /v1/git/connections/:connectionId/repositories/resolve{
"path": "equipe/aplicacao"
}A resposta contém { id, path, default_branch, private, web_url? }. O id é opaco: use-o apenas com a conexão que o retornou. Caminhos podem ter mais de dois componentes, como subgrupos do GitLab; a validação específica fica a cargo do provedor. A resolução explícita funciona mesmo quando a descoberta de repositórios não está disponível.
Quando a conexão anunciar descoberta de repositórios, também é possível listar páginas:
GET /v1/git/connections/:connectionId/repositories?cursor=<opaque-cursor>cursor é opcional e opaco. A resposta contém repositories e next_cursor; uma capacidade não suportada retorna um erro seguro de capacidade, sem solicitar um escopo de acesso mais amplo.
Para listar branches, codifique o ID opaco como um único segmento do caminho:
GET /v1/git/connections/:connectionId/repositories/:repositoryId/branchesA resposta data contém objetos { "name": "main", "commit_sha": "<commit-sha>" }.
Criar e consultar uma origem de projeto
Na criação existente de projeto HTTP, envie config.source e config.build juntos. O exemplo abaixo configura publicação por release. Para usar a publicação manual, omita version_deploy; para usar push na branch, defina auto_deploy como true e omita version_deploy. Não combine source ou build com a configuração legada github.
{
"config": {
"source": {
"connection_id": "connection-id",
"repository_id": "repository-id-from-connection",
"branch": "main",
"auto_deploy": false,
"version_deploy": {
"enabled": true,
"event": "release",
"tag_pattern": "v*",
"include_prereleases": false
}
},
"build": {
"runtime": "nodejs",
"version": "24",
"start_command": "npm start",
"pre_build_command": null,
"build_command": "npm run build",
"dockerfile_path": "Dockerfile",
"context_path": "."
}
}
}Os campos de build são opcionais. O catálogo fornece valores padrão para runtime e versão. Os campos disponíveis são runtime, version, start_command, pre_build_command, build_command, dockerfile_path e context_path.
dockerfile_path deve ser um caminho relativo dentro do repositório, com até 256 caracteres: caminhos absolutos, . ou .. como segmento, barras invertidas e barra no início ou no fim são rejeitados com 400. A branch da origem segue as regras de nomes de branch Git: nomes com espaços, .., @{, iniciados por - ou refs/, ou iguais a HEAD também são rejeitados com 400.
context_path é o diretório raiz do build: a pasta do repositório onde a instalação, o pre-build, o build e o start são executados. É opcional, com padrão "." (raiz do repositório), e vale para a criação, para PUT /project/:id/source e para PATCH /project/:id/build-settings. A API remove espaços nas pontas, o ./ inicial e a / final; caminhos absolutos, .., barras invertidas ou valores com mais de 256 caracteres são rejeitados com 400. Como os demais campos de build, uma alteração em context_path vale a partir do próximo build. As regras completas estão em Diretório raiz do build.
{
"context_path": "apps/api"
}O exemplo acima é um corpo válido para PATCH /project/:id/build-settings.
GET /v1/project/:id/source
PUT /v1/project/:id/source
PATCH /v1/project/:id/build-settings
DELETE /v1/project/:id/source
GET /v1/project/:id/source/branchesPUT /project/:id/source recebe { "source": ..., "build": ... } e retorna a projeção da origem. PATCH /project/:id/build-settings recebe um subconjunto dos campos de build e devolve a mesma projeção. Quando PUT /project/:id/source troca o repositório, a branch ou o build de um projeto que já tinha origem, ou quando PATCH /project/:id/build-settings altera o build, a API inicia um novo build e devolve build_id ao lado de data. Sem project.deploy.trigger, a alteração é salva, nenhum build é iniciado e a resposta traz build_required: true ao lado de data; o próximo deploy manual ou evento configurado aplica a mudança. Se a alteração foi salva, mas o build não pôde começar, a resposta não traz build_id; inicie um deploy manual. GET /project/:id/source/branches lista branches da origem atual. DELETE /project/:id/source retorna a projeção com origem, build e capacidades nulos, interrompe novos deploys dessa origem e preserva a aplicação publicada.
A projeção de GET e PUT tem esta forma:
{
"source": {
"connection_id": "connection-id",
"repository_id": "repository-id-from-connection",
"branch": "main",
"auto_deploy": false,
"version_deploy": {
"enabled": true,
"event": "release",
"tag_pattern": "v*",
"include_prereleases": false
},
"provider_id": "forgejo",
"repository_path": "equipe/aplicacao"
},
"build": {
"runtime": "nodejs",
"version": "24",
"start_command": "npm start",
"dockerfile_path": "Dockerfile",
"context_path": "."
},
"source_revision": 1,
"capabilities": {
"repositoryDiscovery": false,
"pushDeploy": true,
"nativePreviews": false,
"versionDeploy": true
}
}Quando não há origem, source, build e capabilities são null. As revisões são atualizadas pelo servidor quando a origem ou as configurações efetivas mudam. Para a configuração de publicação, auto_deploy: true habilita publicações por push na branch. Para tags ou releases, mantenha auto_deploy: false e habilite version_deploy; os dois modos automáticos não podem ser habilitados juntos. O padrão de tag compara o nome completo, diferencia maiúsculas de minúsculas e aceita apenas * e ? como curingas, com 1 a 255 caracteres. Releases em rascunho não publicam; pré-releases ficam fora por padrão e podem ser incluídas. Em origens GitLab, versionDeploy é false: use só auto_deploy e não envie version_deploy. Consulte Deploy a partir do Forgejo e Deploy a partir do GitLab para os modos e seus requisitos.
O campo source de um DTO de preview tem outro propósito: previews nativos existentes permanecem compatíveis e não devem ser interpretados como essa origem Git.
Erros e limites
Erros usam { "status": "failed", "code": "...", "message": "..." }. Corpo, parâmetros ou query fora do formato são rejeitados antes com 400 e apenas message (Invalid Git request ou Invalid Git source request), sem code.
| Status | Código | Quando ocorre |
|---|---|---|
400 | GIT_INSTANCE_INVALID, GIT_REPOSITORY_INVALID, GIT_SOURCE_INVALID, GIT_BUILD_SETTINGS_INVALID, GIT_REFERENCE_INVALID | Dados inválidos para a instância, o repositório, a origem, o build ou a referência |
401 | — | Escrita de conexões com uma API Key: essas operações exigem a sessão do owner |
403 | GIT_CREDENTIAL_OWNER_SESSION_REQUIRED | Credencial de CLI ou delegada usada para gerenciar credenciais Git |
403 | GIT_PROVIDER_FORBIDDEN | O provedor negou acesso ao recurso (a sessão sem papel de owner recebe 403 com owner role required) |
404 | GIT_CONNECTION_NOT_FOUND, GIT_REPOSITORY_NOT_FOUND, PROJECT_NOT_FOUND | Conexão, repositório ou projeto não encontrado |
409 | GIT_CONNECTION_REVOKED, GIT_CONNECTION_CONFLICT, GIT_CONNECTION_STALE, GIT_TRANSITION_BUSY, GIT_SOURCE_NOT_CONFIGURED, GIT_SOURCE_TRANSITION_PENDING | A conexão foi alterada ou revogada, há uma operação Git em andamento, ou o projeto não tem origem configurada |
409 | GIT_CONNECTION_UNAVAILABLE | A conexão Git selecionada não está disponível para a organização (mensagem The selected Git connection is unavailable.) |
422 | GIT_CREDENTIALS_INVALID | As credenciais não conseguem acessar o repositório selecionado |
429 | GIT_PROVIDER_RATE_LIMITED | O provedor limitou temporariamente as requisições |
501 | GIT_CAPABILITY_UNSUPPORTED | O provedor não oferece a capacidade solicitada |
502, 503 | GIT_PROVIDER_RESPONSE_INVALID, GIT_PROVIDER_UNAVAILABLE, GIT_CONFIGURATION_UNAVAILABLE, GIT_OPERATION_UNAVAILABLE | O provedor ou a integração Git está temporariamente indisponível |
503 | GIT_BUILD_UNAVAILABLE | Na criação de projeto com config.source, o build está temporariamente indisponível; tente novamente em instantes |
Limites de requisições (contados por IP de origem):
| Operação | Limite |
|---|---|
GET /v1/git/providers, GET /v1/git/runtime-catalog | 60 por minuto |
GET /v1/git/connections | 30 por minuto |
POST /v1/git/connections, PATCH /v1/git/connections/:connectionId/credentials, DELETE /v1/git/connections/:connectionId | 5 a cada 5 minutos |
POST /v1/git/connections/:connectionId/repositories/resolve | 30 por minuto |
GET /v1/git/connections/:connectionId/repositories e .../branches | 60 por minuto |
GET /v1/project/:id/source | 50 por minuto |
PUT e DELETE /v1/project/:id/source, PATCH /v1/project/:id/build-settings | 10 por minuto |
GET /v1/project/:id/source/branches | 30 por minuto |
GET /v1/auth/gitlab | 10 por minuto |
GET /v1/auth/gitlab/status | 30 por minuto |
DELETE /v1/auth/gitlab/personal | 5 por minuto |
Próximos passos
Última atualização em
Histórico de Deployments
Consulte o histórico mensal de deployments de um projeto Zenifra via API, com autenticação por API Key, organização ativa e o campo que indica nova imagem.
Builds de repositórios Git
Acompanhe builds de repositórios Git pela API da Zenifra: deploy manual por branch, commit ou tag, modos de publicação GitHub, histórico, detalhe e logs.