API de GitHub

Estos endpoints trabajan con la integración con GitHub de la organización: las cuentas de GitHub donde está instalada la GitHub App de Probara. Instalar la aplicación, desconectar una cuenta, cambiar los repositorios de un proyecto y su ajuste de comentarios en pull requests requieren una sesión iniciada; con un token de API responden 403 forbidden. Todo lo demás funciona con un token de API y con las herramientas MCP.

Todos los endpoints necesitan el plan Pro o Enterprise; en otros planes responden 403 forbidden. Un {projectId} es el código del proyecto, por ejemplo SHOP. Los repositorios se escriben propietario/nombre.

Repositorios que puede usar un proyecto

Un proyecto ofrece los repositorios de su vinculación. Si la vinculación está vacía, ofrece todos los repositorios que ven las instalaciones de la organización. Cada endpoint de esta página que recibe un repository lo comprueba con esa regla.

Método y ruta	Qué hace
GET /api/v1/projects/{projectId}/integrations/github/repositories	La vinculación del proyecto: items con connectionUlid, repositoryId, repositoryFullName e isDefault. Vacía si no hay vinculación.
GET /api/v1/projects/{projectId}/integrations/github/linkable-repositories	Los repositorios que ofrece el proyecto ahora, haya vinculación o no: connectionUlid, repositoryId, fullName e isDefault.
PUT /api/v1/projects/{projectId}/integrations/github/repositories	Sustituye la vinculación por { "repositories": [{ "connectionUlid", "repositoryId", "isDefault" }] }. Solo con sesión, integrations.manage.
GET /api/v1/projects/{projectId}/integrations/github/settings	{ "pullRequestComments": "on_failure" }: cuándo las ejecuciones de GitHub Actions cerradas comentan en su pull request: always, on_failure u off.
PUT /api/v1/projects/{projectId}/integrations/github/settings	Cambia pullRequestComments a always, on_failure u off. Solo con sesión, integrations.manage.

Vincular issues

Los mismos cuatro endpoints existen para casos de prueba, ejecuciones y defectos. {entity} es test-cases/{caseUlid}, runs/{runUlid} o defects/{defectUlid}.

Método y ruta	Qué hace
GET /api/v1/{entity}/github-issues	Lista los vínculos de la entidad.
POST /api/v1/{entity}/github-issues/link	Vincula un issue. Responde 201 con el vínculo.
POST /api/v1/{entity}/github-issues/{linkUlid}/refresh	Vuelve a leer el issue en GitHub y responde el vínculo actualizado.
DELETE /api/v1/{entity}/github-issues/{linkUlid}	Quita el vínculo. El issue sigue en GitHub. Responde 204.

{
  "connectionUlid": "01J9Z3K4M5N6P7Q8R9S0T1V2W3",
  "repository": "acme/shop",
  "issueNumber": 42,
  "linkKind": "requirement"
}

linkKind es requirement o defect, y por defecto vale requirement en un caso de prueba y defect en una ejecución o un defecto. Solo los vínculos defect de un defecto sincronizan el estado del defecto con el issue; los vínculos requirement de los casos de prueba son lo que los informes de trazabilidad de GitHub cuentan como cobertura.

Un vínculo incluye repositoryFullName, issueNumber, linkKind y los datos del issue tal como GitHub los devolvió por última vez: title, state (open o closed), stateReason, labels, authorLogin, htmlUrl e issueUpdatedAt, junto con syncedAt, el momento en que Probara los leyó. Estos datos guardados se devuelven aunque GitHub no responda, y se actualizan con cada cambio del que informa GitHub.

Para leer vínculos hace falta acceso a la entidad. Para cambiarlos hace falta test-cases.write en un caso de prueba, runs.execute en una ejecución y defects.write en un defecto.

Buscar issues de un repositorio

GET /api/v1/projects/{projectId}/integrations/github/issues/search?connectionUlid=…&repository=acme/shop&q=checkout busca issues del repositorio por palabras del título, o lee uno por número con q=42 o q=#42. q admite hasta 200 caracteres y se busca como texto literal: no puede añadir calificadores de búsqueda de GitHub. Devuelve hasta 20 issues, nunca pull requests.

Crear un issue desde un defecto

Método y ruta	Qué hace
GET /api/v1/defects/{defectUlid}/github-issues/draft	El title y el body precargados. Añade ?resultUlid= (un resultado vinculado al defecto) para precargarlos desde ese resultado.
GET /api/v1/projects/{projectId}/integrations/github/labels	Las etiquetas de un repositorio (connectionUlid, repository), con name, color y description.
POST /api/v1/defects/{defectUlid}/github-issues	Crea el issue y lo vincula al defecto como defect.

{
  "connectionUlid": "01J9Z3K4M5N6P7Q8R9S0T1V2W3",
  "repository": "acme/shop",
  "resultUlid": "01J9Z3M7Q2R4S6T8V0W2X4Y6Z8",
  "labels": ["bug"]
}

title (hasta 256 caracteres) y body (Markdown de GitHub, hasta 65 536 caracteres) son opcionales: si no se envían, se usa el borrador, cuyo cuerpo es la descripción del defecto en Markdown, con cada imagen en su URL de recurso almacenada. labels admite hasta 20 nombres del repositorio. Necesita defects.write.

La creación se envía a GitHub una sola vez. Responde 201 con el vínculo nuevo, o 200 cuando un reintento encuentra el issue que abrió una petición anterior. Si se pierde la respuesta de GitHub, la petición responde 409 github_issue_creation_unconfirmed con Retry-After: reintenta pasado ese tiempo y Probara buscará el issue antes de abrir otro.

Lanzar un workflow

Método y ruta	Qué hace
GET /api/v1/projects/{projectId}/integrations/github/workflows	Los workflows activos del repositorio (connectionUlid, repository): id, name y path.
GET /api/v1/projects/{projectId}/integrations/github/branches	Las ramas del repositorio, hasta 500.
POST /api/v1/projects/{projectId}/integrations/github/launches	Crea una ejecución automatizada e inicia el workflow en una rama.

{
  "connectionUlid": "01J9Z3K4M5N6P7Q8R9S0T1V2W3",
  "repository": "acme/shop",
  "ref": "main",
  "workflowId": "probara-e2e.yml",
  "runName": "Nightly E2E"
}

workflowId es un id de la lista de workflows o el nombre del archivo del workflow. runName es, por defecto, el nombre del workflow y la rama. inputs añade hasta 24 inputs de texto más de workflow_dispatch; Probara siempre envía el ULID de la ejecución como probara_run_id. El contrato del workflow está en Ejecutar pruebas con GitHub Actions. Necesita runs.execute y acepta un Idempotency-Key.

• 201: GitHub aceptó el inicio. El cuerpo es la ejecución, con githubBuild.launchStatus dispatched.
• 202: se perdió la respuesta de GitHub. La ejecución se conserva con launchStatus unconfirmed; su build se completa si el workflow llegó a iniciarse.
• Un rechazo (github_workflow_*, github_ref_not_found) no deja ninguna ejecución.

GET /api/v1/runs/{runUlid} devuelve githubBuild en una ejecución lanzada (null en cualquier otra): launchStatus, repository, ref, workflowName, htmlUrl, status, conclusion, runAttempt, startedAt y completedAt. Los campos del build valen null hasta que GitHub informa de la ejecución del workflow. Probara nunca cierra la ejecución a partir del build: la cierra el job final del workflow.

Fuentes de trazabilidad

Las conexiones de GitHub aparecen en GET /api/v1/projects/{projectId}/traceability/sources con provider: "github". Los repositorios, las etiquetas y los hitos que puede usar un informe están en /sources/{connectionUlid}/repositories, /labels?repository= y /milestones?repository=. Consulta la API de informes de trazabilidad.

Errores

Todos los errores usan el formato de error estándar.

Estado	Código	Cuándo
403	forbidden	El plan no incluye integraciones, falta el permiso, o una ruta solo con sesión recibió un token.
403	github_repository_not_mapped	La vinculación del proyecto deja fuera el repositorio.
404	github_issue_not_found	El repositorio no tiene ningún issue con ese número.
404	github_workflow_not_found	El repositorio no tiene ese workflow.
409	github_issue_already_linked	La entidad ya vincula ese issue.
409	github_connection_stale	La instalación se suspendió o se desinstaló en GitHub.
409	github_issue_creation_in_progress	Otra petición está creando el issue de este defecto en ese repositorio.
409	github_issue_creation_unconfirmed	Se perdió la respuesta de GitHub a una creación anterior. Reintenta pasado Retry-After.
422	github_repository_not_visible	La instalación no tiene acceso al repositorio.
422	github_issue_is_pull_request	El número corresponde a un pull request.
422	github_issues_disabled	Los issues están desactivados en el repositorio.
422	github_issue_rejected	GitHub rechazó el issue nuevo, por ejemplo por una etiqueta desconocida.
422	github_workflow_not_dispatchable	El workflow está desactivado o no tiene el disparador workflow_dispatch.
422	github_ref_not_found	El repositorio no tiene esa rama.
422	github_workflow_missing_run_input	El workflow no declara el input probara_run_id en workflow_dispatch.
422	github_workflow_dispatch_failed	GitHub rechazó el inicio, por ejemplo por un input no declarado. details.message incluye el motivo de GitHub.
422	validation_failed	El cuerpo o un parámetro de consulta no es válido.
429	too_many_requests	Se alcanzó el límite de peticiones a GitHub de la organización. Retry-After indica cuándo reintentar.
503	github_app_not_configured	La GitHub App no está configurada en este entorno.
503	github_unavailable	GitHub no responde en este momento.