tcgithub

package
v57.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2023 License: MPL-2.0 Imports: 4 Imported by: 0

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

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 

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.

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 

func (github *Github) GithubWebHookConsumer() error

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 

func (github *Github) Heartbeat() error

Respond with a service heartbeat.

This endpoint is used to check on backing services this service depends on.

See #heartbeat

func (*Github) Latest 

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

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 

func (github *Github) Lbheartbeat() error

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

See #lbheartbeat

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) 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 

func (github *Github) Version() error

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"

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.