Informationen zu Commitstatus

Du kannst die REST-API verwenden, um externen Diensten das Markieren von Commits mit einem error-, failure-, pending- oder success-Status zu erlauben, der sich dann in Pull Requests mit diesen Commits widerspiegelt.

Statuswerte können auch eine optionale `description` und `target_url` enthalten, und es wird dringend empfohlen, sie bereitzustellen, weil dadurch die Statuswerte auf der GitHub-Benutzeroberfläche viel zweckmäßiger sind.

Ein Beispiel für die Verwendung ist für Continuous Integration-Dienste, um Commits als Builds mit dem Status „Übergeben“ oder „Fehler“ zu kennzeichnen. target_url wäre hier die vollständige URL für die Buildausgabe, und description wäre die allgemeine Zusammenfassung der Ereignisse mit dem Build.

Statuswerte können context einschließen, um anzugeben, welcher Dienst diesen Status bereitstellt. Als Beispiel können die Pushstatuswerte deines Continuous Integration-Diensts den Kontext ci und die Pushstatuswerte deines Sicherheitsüberwachungstools den Kontext security besitzen.

Dann kannst du die REST-API zum Abrufen des kombinierten Status für einen bestimmten Verweis verwenden, um den gesamten Status eines Commits abzurufen. Beachte, dass der repo:status-OAuth-Bereich gezielten Zugriff auf Statuswerte ermöglicht, ohne zusätzlich Zugriff auf den Repositorycode zu gewähren. Der repo-Bereich gewährt wiederum Berechtigungen für Code sowie für Statuswerte. Wenn du eine GitHub App entwickelst und genauere Informationen zu einem externen Dienst bereitstellen möchtest, kannst du die REST-API zum Verwalten von Überprüfungen verwenden.

Weitere Informationen findest du unter Prüfungen.

If you are developing a GitHub App and want to provide more detailed information about an external service, you may want to use the REST API to manage checks. For more information, see "Prüfungen."

Get the combined status for a specific reference

Works with 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

Parameters for "Get the combined status for a specific reference"

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository. The name is not case sensitive.
`ref`stringRequired ref parameter
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`page`integer Page number of the results to fetch. Default: `1`

HTTP response status codes for "Get the combined status for a specific reference"

Status code	Description
`200`	OK
`404`	Resource not found

Code samples for "Get the combined status for a specific reference"

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

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

Response

Status: 200

{
  "state": "success",
  "statuses": [
    {
      "url": "https://HOSTNAME/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://HOSTNAME/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://HOSTNAME/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://HOSTNAME/users/octocat/followers",
      "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
      "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
      "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
      "organizations_url": "https://HOSTNAME/users/octocat/orgs",
      "repos_url": "https://HOSTNAME/users/octocat/repos",
      "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
      "received_events_url": "https://HOSTNAME/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://HOSTNAME/repos/octocat/Hello-World",
    "archive_url": "https://HOSTNAME/repos/octocat/Hello-World/{archive_format}{/ref}",
    "assignees_url": "https://HOSTNAME/repos/octocat/Hello-World/assignees{/user}",
    "blobs_url": "https://HOSTNAME/repos/octocat/Hello-World/git/blobs{/sha}",
    "branches_url": "https://HOSTNAME/repos/octocat/Hello-World/branches{/branch}",
    "collaborators_url": "https://HOSTNAME/repos/octocat/Hello-World/collaborators{/collaborator}",
    "comments_url": "https://HOSTNAME/repos/octocat/Hello-World/comments{/number}",
    "commits_url": "https://HOSTNAME/repos/octocat/Hello-World/commits{/sha}",
    "compare_url": "https://HOSTNAME/repos/octocat/Hello-World/compare/{base}...{head}",
    "contents_url": "https://HOSTNAME/repos/octocat/Hello-World/contents/{+path}",
    "contributors_url": "https://HOSTNAME/repos/octocat/Hello-World/contributors",
    "deployments_url": "https://HOSTNAME/repos/octocat/Hello-World/deployments",
    "downloads_url": "https://HOSTNAME/repos/octocat/Hello-World/downloads",
    "events_url": "https://HOSTNAME/repos/octocat/Hello-World/events",
    "forks_url": "https://HOSTNAME/repos/octocat/Hello-World/forks",
    "git_commits_url": "https://HOSTNAME/repos/octocat/Hello-World/git/commits{/sha}",
    "git_refs_url": "https://HOSTNAME/repos/octocat/Hello-World/git/refs{/sha}",
    "git_tags_url": "https://HOSTNAME/repos/octocat/Hello-World/git/tags{/sha}",
    "git_url": "git:github.com/octocat/Hello-World.git",
    "issue_comment_url": "https://HOSTNAME/repos/octocat/Hello-World/issues/comments{/number}",
    "issue_events_url": "https://HOSTNAME/repos/octocat/Hello-World/issues/events{/number}",
    "issues_url": "https://HOSTNAME/repos/octocat/Hello-World/issues{/number}",
    "keys_url": "https://HOSTNAME/repos/octocat/Hello-World/keys{/key_id}",
    "labels_url": "https://HOSTNAME/repos/octocat/Hello-World/labels{/name}",
    "languages_url": "https://HOSTNAME/repos/octocat/Hello-World/languages",
    "merges_url": "https://HOSTNAME/repos/octocat/Hello-World/merges",
    "milestones_url": "https://HOSTNAME/repos/octocat/Hello-World/milestones{/number}",
    "notifications_url": "https://HOSTNAME/repos/octocat/Hello-World/notifications{?since,all,participating}",
    "pulls_url": "https://HOSTNAME/repos/octocat/Hello-World/pulls{/number}",
    "releases_url": "https://HOSTNAME/repos/octocat/Hello-World/releases{/id}",
    "ssh_url": "git@github.com:octocat/Hello-World.git",
    "stargazers_url": "https://HOSTNAME/repos/octocat/Hello-World/stargazers",
    "statuses_url": "https://HOSTNAME/repos/octocat/Hello-World/statuses/{sha}",
    "subscribers_url": "https://HOSTNAME/repos/octocat/Hello-World/subscribers",
    "subscription_url": "https://HOSTNAME/repos/octocat/Hello-World/subscription",
    "tags_url": "https://HOSTNAME/repos/octocat/Hello-World/tags",
    "teams_url": "https://HOSTNAME/repos/octocat/Hello-World/teams",
    "trees_url": "https://HOSTNAME/repos/octocat/Hello-World/git/trees{/sha}",
    "hooks_url": "http://HOSTNAME/repos/octocat/Hello-World/hooks"
  },
  "commit_url": "https://HOSTNAME/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "url": "https://HOSTNAME/repos/octocat/Hello-World/6dcb09b5b57875f334f61aebed695e2e4193db5e/status"
}

List commit statuses for a reference

Works with 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.

Parameters for "List commit statuses for a reference"

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository. The name is not case sensitive.
`ref`stringRequired ref parameter
Query parameters
Name, Type, Description
`per_page`integer The number of results per page (max 100). Default: `30`
`page`integer Page number of the results to fetch. Default: `1`

HTTP response status codes for "List commit statuses for a reference"

Status code	Description
`200`	OK
`301`	Moved permanently

Code samples for "List commit statuses for a reference"

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

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

Response

Status: 200

[
  {
    "url": "https://HOSTNAME/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://HOSTNAME/users/octocat",
      "html_url": "https://github.com/octocat",
      "followers_url": "https://HOSTNAME/users/octocat/followers",
      "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
      "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
      "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
      "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
      "organizations_url": "https://HOSTNAME/users/octocat/orgs",
      "repos_url": "https://HOSTNAME/users/octocat/repos",
      "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
      "received_events_url": "https://HOSTNAME/users/octocat/received_events",
      "type": "User",
      "site_admin": false
    }
  }
]

Create a commit status

Works with 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.

Parameters for "Create a commit status"

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`owner`stringRequired The account owner of the repository. The name is not case sensitive.
`repo`stringRequired The name of the repository. The name is not case sensitive.
`sha`stringRequired
Body parameters
Name, Type, Description
`state`stringRequired The state of the status. Can be one of: `error`, `failure`, `pending`, `success`
`target_url`string or null 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 or null 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. Default: `default`

HTTP response status codes for "Create a commit status"

Status code	Description
`201`	Created

Code samples for "Create a commit status"

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

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-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://HOSTNAME/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://HOSTNAME/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://HOSTNAME/users/octocat/followers",
    "following_url": "https://HOSTNAME/users/octocat/following{/other_user}",
    "gists_url": "https://HOSTNAME/users/octocat/gists{/gist_id}",
    "starred_url": "https://HOSTNAME/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://HOSTNAME/users/octocat/subscriptions",
    "organizations_url": "https://HOSTNAME/users/octocat/orgs",
    "repos_url": "https://HOSTNAME/users/octocat/repos",
    "events_url": "https://HOSTNAME/users/octocat/events{/privacy}",
    "received_events_url": "https://HOSTNAME/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Informationen zu Commitstatus

Statuswerte können auch eine optionale description und target_url enthalten, und es wird dringend empfohlen, sie bereitzustellen, weil dadurch die Statuswerte auf der GitHub-Benutzeroberfläche viel zweckmäßiger sind.

Get the combined status for a specific reference

List commit statuses for a reference

Create a commit status

Statuswerte können auch eine optionale `description` und `target_url` enthalten, und es wird dringend empfohlen, sie bereitzustellen, weil dadurch die Statuswerte auf der GitHub-Benutzeroberfläche viel zweckmäßiger sind.