tcgithub

Documentation

Overview

The github service is responsible for creating tasks in reposnse to GitHub events, and posting results to the GitHub UI.

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.

See:

How to use this package

First create a Github object:

github := tcgithub.New(nil)

and then call one or more of github's methods, e.g.:

err := github.Ping(.....)

handling any errors...

if err != nil {
	// handle error...
}

Taskcluster Schema

The source code of this go package was auto-generated from the API definition at https://taskcluster-staging.net/references/github/v1/api.json together with the input and output schemas it references, downloaded on Thu, 27 Jun 2019 at 07:22:00 UTC. The code was generated by https://github.com/taskcluster/taskcluster-client-go/blob/master/build.sh.

Index

• type Build
• type BuildsResponse
• type CreateCommentRequest
• type CreateStatusRequest
• type Github
  • func New(credentials *tcclient.Credentials, rootURL string) *Github
  • func NewFromEnv() *Github
  • func (github *Github) Badge(owner, repo, branch string) error
  • func (github *Github) Builds(continuationToken, limit, organization, repository, sha string) (*BuildsResponse, error)
  • func (github *Github) CreateComment(owner, repo, number string, payload *CreateCommentRequest) error
  • func (github *Github) CreateStatus(owner, repo, sha string, payload *CreateStatusRequest) error
  • func (github *Github) GithubWebHookConsumer() error
  • func (github *Github) Latest(owner, repo, branch string) error
  • func (github *Github) Ping() error
  • func (github *Github) Repository(owner, repo string) (*RepositoryResponse, error)
• type GithubGUID
• type RepositoryResponse
• type UnknownGithubGUID

Types

type Build

type Build struct {

	// The initial creation time of the build. This is when it became pending.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/created
	Created tcclient.Time `json:"created"`

	// The GitHub webhook deliveryId. Extracted from the header 'X-GitHub-Delivery'
	//
	// One of:
	//   * GithubGUID
	//   * UnknownGithubGUID
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/eventId
	EventID string `json:"eventId"`

	// Type of Github event that triggered the build (i.e. push, pull_request.opened).
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/eventType
	EventType string `json:"eventType"`

	// Github organization associated with the build.
	//
	// Syntax:     ^([a-zA-Z0-9-_%]*)$
	// Min length: 1
	// Max length: 100
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/organization
	Organization string `json:"organization"`

	// Github repository associated with the build.
	//
	// Syntax:     ^([a-zA-Z0-9-_%]*)$
	// Min length: 1
	// Max length: 100
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/repository
	Repository string `json:"repository"`

	// Github revision associated with the build.
	//
	// Min length: 40
	// Max length: 40
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/sha
	Sha string `json:"sha"`

	// Github status associated with the build.
	//
	// Possible values:
	//   * "pending"
	//   * "success"
	//   * "error"
	//   * "failure"
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/state
	State string `json:"state"`

	// Taskcluster task-group associated with the build.
	//
	// Syntax:     ^[A-Za-z0-9_-]{8}[Q-T][A-Za-z0-9_-][CGKOSWaeimquy26-][A-Za-z0-9_-]{10}[AQgw]$
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/taskGroupId
	TaskGroupID string `json:"taskGroupId"`

	// The last updated of the build. If it is done, this is when it finished.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/updated
	Updated tcclient.Time `json:"updated"`
}

See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items

type BuildsResponse

type BuildsResponse struct {

	// A simple list of builds.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds
	Builds []Build `json:"builds"`

	// Passed back from Azure to allow us to page through long result sets.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/continuationToken
	ContinuationToken string `json:"continuationToken,omitempty"`
}

A paginated list of builds

See https://taskcluster-staging.net/schemas/github/v1/build-list.json#

type CreateCommentRequest

type CreateCommentRequest struct {

	// The contents of the comment.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/create-comment.json#/properties/body
	Body string `json:"body"`
}

Write a new comment on a GitHub Issue or Pull Request. Full specification on [GitHub docs](https://developer.github.com/v3/issues/comments/#create-a-comment)

See https://taskcluster-staging.net/schemas/github/v1/create-comment.json#

type CreateStatusRequest

type CreateStatusRequest struct {

	// A string label to differentiate this status from the status of other systems.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/create-status.json#/properties/context
	Context string `json:"context,omitempty"`

	// A short description of the status.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/create-status.json#/properties/description
	Description string `json:"description,omitempty"`

	// The state of the status.
	//
	// Possible values:
	//   * "pending"
	//   * "success"
	//   * "error"
	//   * "failure"
	//
	// See https://taskcluster-staging.net/schemas/github/v1/create-status.json#/properties/state
	State string `json:"state"`

	// 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.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/create-status.json#/properties/target_url
	Target_URL string `json:"target_url,omitempty"`
}

Create a commit status on GitHub. Full specification on [GitHub docs](https://developer.github.com/v3/repos/statuses/#create-a-status)

See https://taskcluster-staging.net/schemas/github/v1/create-status.json#

type Github

type Github tcclient.Client

func New

func New(credentials *tcclient.Credentials, rootURL string) *Github

New returns a Github client, configured to run against production. Pass in nil credentials to create a client without authentication. The returned client is mutable, so returned settings can be altered.

github := tcgithub.New(
    nil,                                      // client without authentication
    "http://localhost:1234/my/taskcluster",   // taskcluster hosted at this root URL on local machine
)
err := github.Ping(.....)                     // for example, call the Ping(.....) API endpoint (described further down)...
if err != nil {
	// handle errors...
}

func NewFromEnv

func NewFromEnv() *Github

NewFromEnv returns a *Github configured from environment variables.

The root URL is taken from TASKCLUSTER_PROXY_URL if set to a non-empty string, otherwise from TASKCLUSTER_ROOT_URL if set, otherwise the empty string.

The credentials are taken from environment variables:

TASKCLUSTER_CLIENT_ID
TASKCLUSTER_ACCESS_TOKEN
TASKCLUSTER_CERTIFICATE

If TASKCLUSTER_CLIENT_ID is empty/unset, authentication will be disabled.

func (*Github) Badge

func (github *Github) Badge(owner, repo, branch string) error

Stability: *** EXPERIMENTAL ***

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

See #badge

func (*Github) Builds

func (github *Github) Builds(continuationToken, limit, organization, repository, sha string) (*BuildsResponse, error)

Stability: *** EXPERIMENTAL ***

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

See #builds

func (*Github) CreateComment

func (github *Github) CreateComment(owner, repo, number string, payload *CreateCommentRequest) error

Stability: *** EXPERIMENTAL ***

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

Required scopes:

github:create-comment:<owner>/<repo>

See #createComment

func (*Github) CreateStatus

func (github *Github) CreateStatus(owner, repo, sha string, payload *CreateStatusRequest) error

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.

Required scopes:

github:create-status:<owner>/<repo>

See #createStatus

func (*Github) GithubWebHookConsumer

func (github *Github) GithubWebHookConsumer() error

Stability: *** EXPERIMENTAL ***

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

See #githubWebHookConsumer

func (*Github) Latest

func (github *Github) Latest(owner, repo, branch string) error

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.

See #latest

func (*Github) Ping

func (github *Github) Ping() error

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

See #ping

func (*Github) Repository

func (github *Github) Repository(owner, repo string) (*RepositoryResponse, error)

Stability: *** EXPERIMENTAL ***

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

See #repository

type GithubGUID

type GithubGUID string

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

Syntax: ^[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}$

See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/eventId/oneOf[0]

type RepositoryResponse

type RepositoryResponse struct {

	// True if integration is installed, False otherwise.
	//
	// See https://taskcluster-staging.net/schemas/github/v1/repository.json#/properties/installed
	Installed bool `json:"installed"`
}

Any Taskcluster-specific Github repository information.

See https://taskcluster-staging.net/schemas/github/v1/repository.json#

type UnknownGithubGUID

type UnknownGithubGUID string

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

Possible values:

• "Unknown"

See https://taskcluster-staging.net/schemas/github/v1/build-list.json#/properties/builds/items/properties/eventId/oneOf[1]