TaskCluster GitHub API Documentation


BaseUrl
https://github.taskcluster.net/v1

The github service, typically available at github.taskcluster.net, is responsible for publishing pulse messages in response to GitHub events.

This document describes the API end-point for consuming GitHub web hooks, as well as some useful consumer APIs.

When Github forbids an action, this service returns an HTTP 403 with code ForbiddenByGithub.

Functions

For more information on invoking the API methods described here, see Using the APIs in the manual.
SignatureSummary
githubWebHookConsumer() : voidConsume GitHub WebHook
builds({continuationToken, limit, organization, repository, sha}) : resultList of Builds
badge(owner, repo, branch) : voidLatest Build Status Badge
repository(owner, repo) : resultGet Repository Info
latest(owner, repo, branch) : voidLatest Status for Branch
createStatus(owner, repo, sha, payload) : voidPost a status against a given changeset
createComment(owner, repo, number, payload) : voidPost a comment on a given GitHub Issue or Pull Request
ping() : voidPing Server

Consume GitHub WebHook

(experimental)

Method
post
Route
/github
Signature
githubWebHookConsumer() : void
Stability
experimental

Capture a GitHub event and publish it via pulse, if it's a push, release or pull request.



List of Builds

(experimental)

Method
get
Route
/builds
Signature
builds({continuationToken, limit, organization, repository, sha}) : result
Stability
experimental

A paginated list of builds that have been run in Taskcluster. Can be filtered on various git-specific fields.

Response

Builds (source)

A paginated list of builds

continuationTokenstring

Passed back from Azure to allow us to page through long result sets.

buildsArray of

A simple list of builds.

organizationstring[1:100]^([a-zA-Z0-9-_%]*)$

Github organization associated with the build.

repositorystring[1:100]^([a-zA-Z0-9-_%]*)$

Github repository associated with the build.

shastring[40:40]

Github revision associated with the build.

statestring
  • pending
  • success
  • error
  • failure

Github status associated with the build.

taskGroupIdstring^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$

Taskcluster task-group associated with the build.

eventTypestring

Type of Github event that triggered the build (i.e. push, pull_request.opened).

eventIdOne of

The GitHub webhook deliveryId. Extracted from the header 'X-GitHub-Delivery'

string^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$
stringUnknown
createdstringdate-time

The initial creation time of the build. This is when it became pending.

updatedstringdate-time

The last updated of the build. If it is done, this is when it finished.



Latest Build Status Badge

(experimental)

Method
get
Route
/repository/<owner>/<repo>/<branch>/badge.svg
Signature
badge(owner, repo, branch) : void
Stability
experimental

Checks the status of the latest build of a given branch and returns corresponding badge svg.



Get Repository Info

(experimental)

Method
get
Route
/repository/<owner>/<repo>
Signature
repository(owner, repo) : result
Stability
experimental

Returns any repository metadata that is useful within Taskcluster related services.

Response

repository (source)

Any Taskcluster-specific Github repository information.

installedboolean

True if integration is installed, False otherwise.



Latest Status for Branch

(experimental)

Method
get
Route
/repository/<owner>/<repo>/<branch>/latest
Signature
latest(owner, repo, branch) : void
Stability
experimental

For a given branch of a repository, this will always point to a status page for the most recent task triggered by that branch.

Note: This is a redirect rather than a direct link.



Post a status against a given changeset

(experimental)

Method
post
Route
/repository/<owner>/<repo>/statuses/<sha>
Scopes
github:create-status:<owner>/<repo>
Signature
createStatus(owner, repo, sha, payload) : void
Stability
experimental

For a given changeset (SHA) of a repository, this will attach a "commit status" on github. These statuses are links displayed next to each revision. The status is either OK (green check) or FAILURE (red cross), made of a custom title and link.

Request Payload

Create status (source)

Create a commit status on GitHub. Full specification on GitHub docs

statestring
  • pending
  • success
  • error
  • failure

The state of the status.

target_urlstring

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.

descriptionstring

A short description of the status.

contextstring

A string label to differentiate this status from the status of other systems.



Post a comment on a given GitHub Issue or Pull Request

(experimental)

Method
post
Route
/repository/<owner>/<repo>/issues/<number>/comments
Scopes
github:create-comment:<owner>/<repo>
Signature
createComment(owner, repo, number, payload) : void
Stability
experimental

For a given Issue or Pull Request of a repository, this will write a new message.

Request Payload

Create comment (source)

Write a new comment on a GitHub Issue or Pull Request. Full specification on GitHub docs

bodystring

The contents of the comment.



Ping Server

Method
get
Route
/ping
Signature
ping() : void
Stability
stable

Respond without doing anything. This endpoint is used to check that the service is up.