Documentation ¶
Overview ¶
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"