Documentation ¶
Overview ¶
This package was generated from the schema defined at /references/github/v1/api.json The github service is responsible for creating tasks in response 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 ¶
- type Build
- type BuildsResponse
- type CreateCommentRequest
- type CreateStatusRequest
- type Github
- func (github *Github) Badge(owner, repo, branch string) error
- func (github *Github) Badge_SignedURL(owner, repo, branch string, duration time.Duration) (*url.URL, error)
- func (github *Github) Builds(continuationToken, limit, organization, repository, sha string) (*BuildsResponse, error)
- func (github *Github) Builds_SignedURL(continuationToken, limit, organization, repository, sha string, ...) (*url.URL, 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) Heartbeat() error
- func (github *Github) Latest(owner, repo, branch string) error
- func (github *Github) Latest_SignedURL(owner, repo, branch string, duration time.Duration) (*url.URL, error)
- func (github *Github) Lbheartbeat() error
- func (github *Github) Ping() error
- func (github *Github) Repository(owner, repo string) (*RepositoryResponse, error)
- func (github *Github) Repository_SignedURL(owner, repo string, duration time.Duration) (*url.URL, error)
- func (github *Github) Version() error
- type GithubGUID
- type RepositoryResponse
- type UnknownGithubGUID
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 ¶
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 ¶
Stability: *** EXPERIMENTAL ***
Checks the status of the latest build of a given branch and returns corresponding badge svg.
Required scopes:
github:get-badge:<owner>:<repo>:<branch>
See #badge
func (*Github) Badge_SignedURL ¶
func (github *Github) Badge_SignedURL(owner, repo, branch string, duration time.Duration) (*url.URL, error)
Returns a signed URL for Badge, valid for the specified duration.
Required scopes:
github:get-badge:<owner>:<repo>:<branch>
See Badge for more details.
func (*Github) Builds ¶
func (github *Github) Builds(continuationToken, limit, organization, repository, sha string) (*BuildsResponse, error)
A paginated list of builds that have been run in Taskcluster. Can be filtered on various git-specific fields.
Required scopes:
github:list-builds
See #builds
func (*Github) Builds_SignedURL ¶
func (github *Github) Builds_SignedURL(continuationToken, limit, organization, repository, sha string, duration time.Duration) (*url.URL, error)
Returns a signed URL for Builds, valid for the specified duration.
Required scopes:
github:list-builds
See Builds for more details.
func (*Github) CreateComment ¶
func (github *Github) CreateComment(owner, repo, number string, payload *CreateCommentRequest) error
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 ¶
Capture a GitHub event and publish it via pulse, if it's a push, release, check run or pull request.
See #githubWebHookConsumer
func (*Github) Heartbeat ¶ added in v44.8.2
Respond with a service heartbeat.
This endpoint is used to check on backing services this service depends on.
See #heartbeat
func (*Github) Latest ¶
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.
Required scopes:
github:latest-status:<owner>:<repo>:<branch>
See #latest
func (*Github) Latest_SignedURL ¶
func (github *Github) Latest_SignedURL(owner, repo, branch string, duration time.Duration) (*url.URL, error)
Returns a signed URL for Latest, valid for the specified duration.
Required scopes:
github:latest-status:<owner>:<repo>:<branch>
See Latest for more details.
func (*Github) Lbheartbeat ¶ added in v44.8.0
Respond without doing anything. This endpoint is used to check that the service is up.
See #lbheartbeat
func (*Github) Ping ¶
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.
Required scopes:
github:get-repository:<owner>:<repo>
See #repository
func (*Github) Repository_SignedURL ¶
func (github *Github) Repository_SignedURL(owner, repo string, duration time.Duration) (*url.URL, error)
Returns a signed URL for Repository, valid for the specified duration.
Required scopes:
github:get-repository:<owner>:<repo>
See Repository for more details.
func (*Github) Version ¶ added in v44.8.0
Respond with the JSON version object. https://github.com/mozilla-services/Dockerflow/blob/main/docs/version_object.md
See #version
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"