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, pullRequest, repository, sha string) (*BuildsResponse, error)
- func (github *Github) Builds_SignedURL(continuationToken, limit, organization, pullRequest, repository, sha string, ...) (*url.URL, error)
- func (github *Github) CancelBuilds(owner, repo, pullRequest, 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) 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) RenderTaskclusterYml(payload *RenderTaskclusterYmlInput) (*RenderTaskclusterYmlOutput, 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 PullRequestEvents
- type PushEvents
- type ReleaseEvents
- type RenderTaskclusterYmlInput
- type RenderTaskclusterYmlOutput
- 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"`
// Associated pull request number for 'pull_request' events.
PullRequestNumber int64 `json:"pullRequestNumber,omitempty"`
// 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"
// * "cancelled"
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, pullRequest, 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, pullRequest, 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) CancelBuilds ¶
func (github *Github) CancelBuilds(owner, repo, pullRequest, sha string) (*BuildsResponse, error)
Cancel all running Task Groups associated with given repository and sha or pullRequest number
Required scopes:
github:cancel-builds:<owner>:<repo>
See #cancelBuilds
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 ¶
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 ¶
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) RenderTaskclusterYml ¶
func (github *Github) RenderTaskclusterYml(payload *RenderTaskclusterYmlInput) (*RenderTaskclusterYmlOutput, error)
Stability: *** EXPERIMENTAL ***
This endpoint allows to render the .taskcluster.yml file for a given event or payload. This is useful to preview the result of the .taskcluster.yml file before pushing it to the repository. Read more about the .taskcluster.yml file in the [documentation](https://docs.taskcluster.net/docs/reference/integrations/github/taskcluster-yml-v1)
See #renderTaskclusterYml
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 ¶
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 PullRequestEvents ¶
type PullRequestEvents struct {
// Possible values:
// * "opened"
// * "synchronize"
// * "reopened"
// * "assigned"
// * "auto_merge_disabled"
// * "auto_merge_enabled"
// * "closed"
// * "converted_to_draft"
// * "dequeued"
// * "edited"
// * "enqueued"
// * "labeled"
// * "ready_for_review"
// * "review_requested"
// * "review_request_removed"
// * "unassigned"
// * "unlabeled"
Action string `json:"action"`
// Additional data to be mixed to the mocked event object.
// This can be used to set some specific properties of the event or override the existing ones.
// For example:
// "ref": "refs/heads/main"
// "before": "000"
// "after": "111"
// To make sure which properties are available for each event type,
// please refer to the github [documentation](https://docs.github.com/en/webhooks-and-events/webhooks/webhook-events-and-payloads)
//
// Additional properties allowed
Overrides json.RawMessage `json:"overrides,omitempty"`
// Possible values:
// * "github-pull-request"
// * "github-pull-request-untrusted"
Type string `json:"type"`
}
.taskcluster.yml supports `github-pull-request` and `github-pull-request-untrusted` events. The difference is that `github-pull-request-untrusted` will use different set of scopes. See [RFC 175](https://github.com/taskcluster/taskcluster-rfcs/blob/main/rfcs/0175-restricted-pull-requests.md)
type PushEvents ¶
type PushEvents struct {
// Additional data to be mixed to the mocked event object.
// This can be used to set some specific properties of the event or override the existing ones.
// For example:
// "ref": "refs/heads/main"
// "before": "000"
// "after": "111"
// To make sure which properties are available for each event type,
// please refer to the github [documentation](https://docs.github.com/en/webhooks-and-events/webhooks/webhook-events-and-payloads)
//
// Additional properties allowed
Overrides json.RawMessage `json:"overrides,omitempty"`
// Possible values:
// * "github-push"
Type string `json:"type"`
}
Github sends `push` event for commits and for tags. To distinguish between those two, the `ref` property is used. If you want to mock a tag push, please specify `ref` property in the overrides: "ref": "refs/tags/v1.0.0"
type ReleaseEvents ¶
type ReleaseEvents struct {
// Possible values:
// * "published"
// * "unpublished"
// * "created"
// * "edited"
// * "deleted"
// * "prereleased"
// * "released"
Action string `json:"action"`
// Additional data to be mixed to the mocked event object.
// This can be used to set some specific properties of the event or override the existing ones.
// For example:
// "ref": "refs/heads/main"
// "before": "000"
// "after": "111"
// To make sure which properties are available for each event type,
// please refer to the github [documentation](https://docs.github.com/en/webhooks-and-events/webhooks/webhook-events-and-payloads)
//
// Additional properties allowed
Overrides json.RawMessage `json:"overrides,omitempty"`
// Possible values:
// * "github-release"
Type string `json:"type"`
}
Emulate one of the github events with mocked payload. Some of the events have sub-actions, that can be specified. Event type names follow the `tasks_for` naming convention.
type RenderTaskclusterYmlInput ¶
type RenderTaskclusterYmlInput struct {
// The contents of the .taskcluster.yml file.
Body string `json:"body"`
// Emulate one of the github events with mocked payload.
// Some of the events have sub-actions, that can be specified.
// Event type names follow the `tasks_for` naming convention.
//
// One of:
// * PushEvents
// * PullRequestEvents
// * ReleaseEvents
FakeEvent json.RawMessage `json:"fakeEvent"`
// Syntax: ^[-a-zA-Z0-9]{1,39}$
Organization string `json:"organization,omitempty"`
// Syntax: ^[-a-zA-Z0-9_.]{1,100}$
Repository string `json:"repository,omitempty"`
}
Render .taskcluster.yml for one of the supported events.
Read more about the `.taskcluster.yml` file format in [documentation](https://docs.taskcluster.net/docs/reference/integrations/github/taskcluster-yml-v1)
type RenderTaskclusterYmlOutput ¶
type RenderTaskclusterYmlOutput struct {
// Scopes that will be used by the github client to create tasks.
// Those are different that the scopes inside the tasks itself.
//
// Array items:
Scopes []string `json:"scopes"`
// Rendered tasks objects.
// Those objects not guaranteed to produce valid task definitions
// that conform to the json schema.
//
// Array items:
// Additional properties allowed
Tasks []json.RawMessage `json:"tasks"`
}
Rendered .taskcluster.yml output.
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"