Conexões e origens Git

Use estes endpoints para consultar capacidades Git, gerenciar uma conexão Forgejo, 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.

Consultar capacidades e runtimes

GET /v1/git/providers
GET /v1/git/runtime-catalog

GET /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 e Forgejo; uma integração GitLab não 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

Listar conexões

GET /v1/git/connections

Retorna 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.

Criar conexão

POST /v1/git/connections

O corpo exige os campos abaixo e retorna 201. Use uma URL HTTPS com certificado confiável e o caminho explícito do repositório; Forgejo não oferece descoberta de repositórios atualmente. 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.

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.

Atualizar credencial

PATCH /v1/git/connections/:connectionId/credentials

O corpo aceita repository_path, username e token. A credencial substituída não é exibida. 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/:connectionId

Quando 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. A gestão da autorização GitHub existente continua nas rotas OAuth atuais.

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; 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/branches

A 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.

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/branches

PUT /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. 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. Consulte Deploy a partir do Forgejo 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.

Limites de requisições (contados por IP de origem):

Próximos passos

• Deploy a partir do Forgejo
• Builds de repositórios Git
• CLI de Deploy e Automação