tcgithub

package
Version: v19.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 7, 2019 License: MPL-2.0 Imports: 2 Imported by: 0

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 <rootUrl>/references/github/v1/api.json together with the input and output schemas it references,

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Build

type Build struct {

	// The initial creation time of the build. This is when it became pending.
	Created tcclient.Time `json:"created"`

	// The GitHub webhook deliveryId. Extracted from the header 'X-GitHub-Delivery'
	//
	// One of:
	//   * GithubGUID
	//   * UnknownGithubGUID
	EventID string `json:"eventId"`

	// Type of Github event that triggered the build (i.e. push, pull_request.opened).
	EventType string `json:"eventType"`

	// Github organization associated with the build.
	//
	// Syntax:     ^([a-zA-Z0-9-_%]*)$
	// Min length: 1
	// Max length: 100
	Organization string `json:"organization"`

	// Github repository associated with the build.
	//
	// Syntax:     ^([a-zA-Z0-9-_%]*)$
	// Min length: 1
	// Max length: 100
	Repository string `json:"repository"`

	// Github revision associated with the build.
	//
	// Min length: 40
	// Max length: 40
	Sha string `json:"sha"`

	// Github status associated with the build.
	//
	// Possible values:
	//   * "pending"
	//   * "success"
	//   * "error"
	//   * "failure"
	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]$
	TaskGroupID string `json:"taskGroupId"`

	// The last updated of the build. If it is done, this is when it finished.
	Updated tcclient.Time `json:"updated"`
}

type BuildsResponse

type BuildsResponse struct {

	// A simple list of builds.
	Builds []Build `json:"builds"`

	// Passed back from Azure to allow us to page through long result sets.
	ContinuationToken string `json:"continuationToken,omitempty"`
}

A paginated list of builds

type CreateCommentRequest

type CreateCommentRequest struct {

	// The contents of the comment.
	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)

type CreateStatusRequest

type CreateStatusRequest struct {

	// A string label to differentiate this status from the status of other systems.
	Context string `json:"context,omitempty"`

	// A short description of the status.
	Description string `json:"description,omitempty"`

	// The state of the status.
	//
	// Possible values:
	//   * "pending"
	//   * "success"
	//   * "error"
	//   * "failure"
	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.
	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)

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}$

type RepositoryResponse

type RepositoryResponse struct {

	// True if integration is installed, False otherwise.
	Installed bool `json:"installed"`
}

Any Taskcluster-specific Github repository information.

type UnknownGithubGUID

type UnknownGithubGUID string

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

Possible values:

* "Unknown"

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL