Estados de confirmación

The Commit status API allows external services to mark commits with a status, which is then reflected in pull requests involving those commits.

About the Commit statuses API

The Commit status API allows external services to mark commits with an error, failure, pending, or success state, which is then reflected in pull requests involving those commits. Statuses can also include an optional description and target_url, and we highly recommend providing them as they make statuses much more useful in the GitHub UI.

As an example, one common use is for continuous integration services to mark commits as passing or failing builds using status. The target_url would be the full URL to the build output, and the description would be the high level summary of what happened with the build.

Los estados pueden incluir un context para indicar qué servicio está proporcionando ese estado. Por ejemplo, puedes hacer que tu servicio de integración continua cargue estados con un contexto de ci, y que una herramienta de auditoria de seguridad cargue estados con un contexto de security. You can then use the Get the combined status for a specific reference to retrieve the whole status for a commit.

Note that the repo:status OAuth scope grants targeted access to statuses without also granting access to repository code, while the repo scope grants permission to code as well as statuses.

Si estás desarrollando una GitHub App y quieres proporcionar información más detallada sobre un servicio externo, tal vez quieras utilizar la API de Verificaciones.

Get the combined status for a specific reference

Funciona con GitHub Apps

Users with pull access in a repository can access a combined view of commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name.

Additionally, a combined state is returned. The state is one of:

failure if any of the contexts report as error or failure
pending if there are no statuses or a context is pending
success if the latest status for all contexts is success

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`owner`stringRequerido The account owner of the repository. The name is not case sensitive.
`repo`stringRequerido The name of the repository. The name is not case sensitive.
`ref`stringRequerido ref parameter
Parámetros de consulta
Nombre, Tipo, Descripción
`per_page`integer The number of results per page (max 100). Predeterminado: `30`
`page`integer Page number of the results to fetch. Predeterminado: `1`

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK
`404`	Resource not found

Ejemplos de código

get/repos/{owner}/{repo}/commits/{ref}/status

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/commits/REF/status

Response

Status: 200

{
  "state": "success",
  "statuses": [
    {
      "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "avatar_url": "https://github.com/images/error/hubot_happy.gif",
      "id": 1,
      "node_id": "MDY6U3RhdHVzMQ==",
      "state": "success",
      "description": "Build has completed successfully",
      "target_url": "https://ci.example.com/1000/output",
      "context": "continuous-integration/jenkins",
      "created_at": "2012-07-20T01:19:13Z",
      "updated_at": "2012-07-20T01:19:13Z"
    },
    {
      "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
      "avatar_url": "https://github.com/images/error/other_user_happy.gif",
      "id": 2,
      "node_id": "MDY6U3RhdHVzMg==",
      "state": "success",
      "description": "Testing has completed successfully",
      "target_url": "https://ci.example.com/2000/output",
      "context": "security/brakeman",
      "created_at": "2012-08-20T01:19:13Z",
      "updated_at": "2012-08-20T01:19:13Z"
    }
  ],
  "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "total_count": 2,
  "repository": {
    "id": 1296269,
    "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
    "name": "Hello-World",
    "full_name": "octocat/Hello-World",
    "owner": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    },
    "private": false,
    "html_url": "https://github.com/octocat/Hello-World",
    "description": "This your first repo!",
    "fork": false,
    "url": "https://api.github.com/repos/octocat/Hello-World",
    "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
    "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
    "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
    "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
    "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
    "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
    "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
    "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
    "hooks_url": "http://api.github.com/repos/octocat/Hello-World/hooks"
  },
  "commit_url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "url": "https://api.github.com/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e/status"
}

List commit statuses for a reference

Funciona con GitHub Apps

Users with pull access in a repository can view commit statuses for a given ref. The ref can be a SHA, a branch name, or a tag name. Statuses are returned in reverse chronological order. The first status in the list will be the latest one.

This resource is also available via a legacy route: GET /repos/:owner/:repo/statuses/:ref.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`owner`stringRequerido The account owner of the repository. The name is not case sensitive.
`repo`stringRequerido The name of the repository. The name is not case sensitive.
`ref`stringRequerido ref parameter
Parámetros de consulta
Nombre, Tipo, Descripción
`per_page`integer The number of results per page (max 100). Predeterminado: `30`
`page`integer Page number of the results to fetch. Predeterminado: `1`

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`200`	OK
`301`	Moved permanently

Ejemplos de código

get/repos/{owner}/{repo}/commits/{ref}/statuses

curl \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/commits/REF/statuses

Response

Status: 200

[
  {
    "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
    "avatar_url": "https://github.com/images/error/hubot_happy.gif",
    "id": 1,
    "node_id": "MDY6U3RhdHVzMQ==",
    "state": "success",
    "description": "Build has completed successfully",
    "target_url": "https://ci.example.com/1000/output",
    "context": "continuous-integration/jenkins",
    "created_at": "2012-07-20T01:19:13Z",
    "updated_at": "2012-07-20T01:19:13Z",
    "creator": {
      "login": "octocat",
      "id": 1,
      "node_id": "MDQ6VXNlcjE=",
      "avatar_url": "https://github.com/images/error/octocat_happy.gif",
      "gravatar_id": "",
      "url": "https://api.github.com/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://api.github.com/users/octocat/followers",
      "following_url": "https://api.github.com/users/octocat/following{/other_user}",
      "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
      "organizations_url": "https://api.github.com/users/octocat/orgs",
      "repos_url": "https://api.github.com/users/octocat/repos",
      "events_url": "https://api.github.com/users/octocat/events{/privacy}",
      "received_events_url": "https://api.github.com/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    }
  }
]

Create a commit status

Funciona con GitHub Apps

Users with push access in a repository can create commit statuses for a given SHA.

Note: there is a limit of 1000 statuses per sha and context within a repository. Attempts to create more than 1000 statuses will result in a validation error.

Parámetros

Encabezados
Nombre, Tipo, Descripción
`accept`string Setting to `application/vnd.github.v3+json` is recommended.
Parámetros de ruta
Nombre, Tipo, Descripción
`owner`stringRequerido The account owner of the repository. The name is not case sensitive.
`repo`stringRequerido The name of the repository. The name is not case sensitive.
`sha`stringRequerido
Parámetros de cuerpo
Nombre, Tipo, Descripción
`state`stringRequerido The state of the status. Puede ser una de las siguientes: `error`, `failure`, `pending`, `success`
`target_url`string The target URL to associate with this status. This URL will be linked from the GitHub UI to allow users to easily see the source of the status. For example, if your continuous integration system is posting build status, you would want to provide the deep link for the build output for this specific SHA: `http://ci.example.com/user/repo/build/sha`
`description`string A short description of the status.
`context`string A string label to differentiate this status from the status of other systems. This field is case-insensitive. Predeterminado: `default`

Códigos de estado de respuesta HTTP

Código de estado	Descripción
`201`	Created

Ejemplos de código

post/repos/{owner}/{repo}/statuses/{sha}

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \ 
  -H "Authorization: token <TOKEN>" \
  http(s)://HOSTNAME/api/v3/repos/OWNER/REPO/statuses/SHA \
  -d '{"state":"success","target_url":"https://example.com/build/status","description":"The build succeeded!","context":"continuous-integration/jenkins"}'

Response

Status: 201

{
  "url": "https://api.github.com/repos/octocat/Hello-World/statuses/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "avatar_url": "https://github.com/images/error/hubot_happy.gif",
  "id": 1,
  "node_id": "MDY6U3RhdHVzMQ==",
  "state": "success",
  "description": "Build has completed successfully",
  "target_url": "https://ci.example.com/1000/output",
  "context": "continuous-integration/jenkins",
  "created_at": "2012-07-20T01:19:13Z",
  "updated_at": "2012-07-20T01:19:13Z",
  "creator": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}