github

package
v0.999.0 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2025 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ErrAPIRateLimitExceeded is returned when the API rate limit is exceeded
	ErrAPIRateLimitExceeded = "API rate limit already exceeded"
	// ErrAPIRateLimitExceededFinalAttempt is returned when the API rate limit is exceeded and no more retry is possible
	ErrAPIRateLimitExceededFinalAttempt = "API rate limit exceeded, final attempt failed"
)

Variables

View Source
var (
	// ErrAutomergeNotAllowOnRepository is returned when automerge is not allowed on the repository
	ErrAutomergeNotAllowOnRepository = errors.New("automerge is not allowed on repository")
	// ErrBadMergeMethod is returned when the merge method is not valid
	ErrBadMergeMethod = errors.New("wrong merge method defined, accepting one of 'squash', 'merge', 'rebase', or ''")
	// ErrPullRequestIsInCleanStatus is returned when the pull request is in clean status
	ErrPullRequestIsInCleanStatus = errors.New("pull request Pull request is in clean status")
)

Functions

This section is empty.

Types

type ActionSpec added in v0.40.0

type ActionSpec struct {
	// automerge allows to enable/disable the automerge feature on new pullrequest
	//
	// compatible:
	//   * action
	//
	// default:
	//   false
	AutoMerge bool `yaml:",omitempty"`
	// title allows to override the pull request title
	//
	// compatible:
	//   * action
	//
	// default:
	//   The default title is fetch from the first following location:
	//   1. The action title
	//   2. The target title if only one target
	//   3. The pipeline target
	//
	Title string `yaml:",omitempty"`
	// description allows to prepend information to the pullrequest description.
	//
	// compatible:
	//   * action
	//
	// default:
	//   empty
	//
	Description string `yaml:",omitempty"`
	// labels specifies repository labels used for the Pull Request.
	//
	// compatible:
	//   * action
	//
	// default:
	//    empty
	//
	// remark:
	//   Labels must already exist on the repository
	//
	Labels []string `yaml:",omitempty"`
	// draft allows to set pull request in draft
	//
	// compatible:
	//   * action
	//
	// default:
	//   false
	Draft bool `yaml:",omitempty"`
	// maintainercannotmodify allows to specify if maintainer can modify pullRequest
	//
	// compatible:
	//   * action
	//
	// default:
	//   false
	MaintainerCannotModify bool `yaml:",omitempty"`
	// mergemethod allows to specifies what merge method is used to incorporate the pull request.
	//
	// compatible:
	//   * action
	//
	// default:
	//   ""
	//
	// remark:
	//   Accept "merge", "squash", "rebase", or ""
	MergeMethod string `yaml:",omitempty"`
	// usetitleforautomerge allows to specifies to use the Pull Request title as commit message when using auto merge,
	//
	// compatible:
	//   * action
	//
	// default:
	//   ""
	//
	// remark:
	//   Only works for "squash" or "rebase"
	UseTitleForAutoMerge bool `yaml:",omitempty"`
	// parent allows to specifies if a pull request should be sent to the parent of the current fork.
	//
	// compatible:
	//   * action
	//
	// default:
	//   false
	//
	Parent bool `yaml:",omitempty"`

	// Reviewers contains the list of assignee to add to the pull request
	// compatible:
	//   * action
	//
	// default: empty
	//
	// remark:
	//   * if reviewer is a team, the format is "organization/team" and the token must have organization read permission.
	Reviewers []string `yaml:",omitempty"`

	// Assignees contains the list of assignee to add to the pull request
	//
	// default: empty
	//
	// remark:
	//   * Please note that contrary to reviewers, assignees only accept GitHub usernames
	Assignees []string `yaml:",omitempty"`
}

ActionSpec specifies the configuration of an action of type "GitHub Pull Request"

func (*ActionSpec) Validate added in v0.40.0

func (s *ActionSpec) Validate() error

Validate ensures that the provided ActionSpec is valid

type Github

type Github struct {

	// Spec contains inputs coming from updatecli configuration
	Spec Spec
	// contains filtered or unexported fields
}

GitHub contains settings to interact with GitHub

func New

func New(s Spec, pipelineID string) (*Github, error)

New returns a new valid GitHub object.

func (*Github) Add

func (g *Github) Add(files []string) error

Add run `git add`.

func (*Github) Changelog

func (g *Github) Changelog(version version.Version) (string, error)

Changelog returns a changelog description based on a release name

func (*Github) Checkout

func (g *Github) Checkout() error

Checkout create and then uses a temporary git branch.

func (*Github) Clean

func (g *Github) Clean() error

Clean deletes github working directory.

func (*Github) Clone

func (g *Github) Clone() (string, error)

Clone run `git clone`.

func (*Github) Commit

func (g *Github) Commit(message string) error

Commit run `git commit`.

func (*Github) CreateCommit added in v0.76.0

func (g *Github) CreateCommit(workingDir string, commitMessage string, retry int) (createdCommitHash string, err error)

CreateCommit creates a commit on a branch using GitHub API

func (*Github) GetBranches added in v0.53.0

func (g *Github) GetBranches() (sourceBranch, workingBranch, targetBranch string)

GetBranches returns source, working and target branch

func (*Github) GetChangedFiles

func (g *Github) GetChangedFiles(workingDir string) ([]string, error)

GetChangedFiles returns a list of changed files in the working directory

func (*Github) GetDirectory

func (g *Github) GetDirectory() (directory string)

GetDirectory returns the local git repository path.

func (*Github) GetLatestCommitHash added in v0.76.1

func (g *Github) GetLatestCommitHash(workingBranch string) (*RepositoryRef, error)

GetLatestCommitHash returns the latest commit hash of the specified branch

func (*Github) GetURL added in v0.53.0

func (g *Github) GetURL() string

GetURL returns a "GitHub " git URL

func (*Github) IsRemoteBranchUpToDate added in v0.45.0

func (g *Github) IsRemoteBranchUpToDate() (bool, error)

IsRemoteBranchUpToDate checks if the branch reference name is published on on the default remote

func (*Github) Push

func (g *Github) Push() (bool, error)

Push run `git push` on the GitHub remote branch if not already created.

func (*Github) PushBranch added in v0.44.0

func (g *Github) PushBranch(branch string) error

PushBranch push tags

func (*Github) PushTag

func (g *Github) PushTag(tag string) error

PushTag push tags

func (*Github) SearchReleases

func (g *Github) SearchReleases(releaseType ReleaseType, retry int) (releases []ReleaseNode, err error)

SearchReleases return every releaseNode from the github api ordered by reverse order of created time. Draft and pre-releases are filtered out.

func (*Github) SearchReleasesByTagHash added in v0.92.0

func (g *Github) SearchReleasesByTagHash(releaseType ReleaseType) (releases []string, err error)

SearchReleasesByTagHash return every releases tag hash from the github api ordered by reverse order of created time. Draft and pre-releases are filtered out.

func (*Github) SearchReleasesByTagName added in v0.92.0

func (g *Github) SearchReleasesByTagName(releaseType ReleaseType) (releases []string, err error)

SearchReleasesByTagName return every releases tag name from the github api ordered by reverse order of created time. Draft and pre-releases are filtered out.

func (*Github) SearchReleasesByTitle added in v0.97.0

func (g *Github) SearchReleasesByTitle(releaseType ReleaseType) (releases []string, err error)

SearchReleasesByTitle return every releases title from the github api ordered by reverse order of created time. Draft and pre-releases are filtered out.

func (*Github) SearchTags

func (g *Github) SearchTags(retry int) (tags []string, err error)

SearchTags return every tags from the github api return in reverse order of commit tags.

type GithubHandler

type GithubHandler interface {
	SearchReleases(releaseType ReleaseType, retry int) (releases []ReleaseNode, err error)
	SearchReleasesByTagName(releaseType ReleaseType) (releases []string, err error)
	SearchReleasesByTagHash(releaseType ReleaseType) (releases []string, err error)
	SearchReleasesByTitle(releaseType ReleaseType) (releases []string, err error)
	SearchTags(retry int) (tags []string, err error)
	Changelog(version.Version) (string, error)
}

GithubHandler must be implemented by any GitHub module

type MockGitHubClient

type MockGitHubClient struct {
	// contains filtered or unexported fields
}

MockGitHubClient is a mock implementation of the GitHubClient interface

func (*MockGitHubClient) Mutate

func (mock *MockGitHubClient) Mutate(ctx context.Context, m interface{}, input githubv4.Input, variables map[string]interface{}) error

Mutate is a mock implementation of the Mutate method of the GitHubClient interface

func (*MockGitHubClient) Query

func (mock *MockGitHubClient) Query(ctx context.Context, q interface{}, variables map[string]interface{}) error

Query is a mock implementation of the Query method of the GitHubClient interface

type PageInfo

type PageInfo struct {
	HasNextPage     bool
	HasPreviousPage bool
	EndCursor       string
	StartCursor     string
}

PageInfo is used for Graphql queries to iterate over pagination

type PullRequest

type PullRequest struct {
	Report string
	Title  string
	// contains filtered or unexported fields
}

PullRequest contains multiple fields mapped to GitHub V4 api

func NewAction added in v0.40.0

func NewAction(spec ActionSpec, gh *Github) (PullRequest, error)

func (*PullRequest) CheckActionExist added in v0.89.0

func (p *PullRequest) CheckActionExist(report *reports.Action) error

CheckActionExist checks if a pullrequest already exists and update the report object accordingly

func (*PullRequest) CleanAction added in v0.75.0

func (p *PullRequest) CleanAction(report *reports.Action) error

CleanAction verifies if an existing action requires some cleanup such as closing a pullrequest with no changes.

func (*PullRequest) CreateAction added in v0.40.0

func (p *PullRequest) CreateAction(report *reports.Action, resetDescription bool) error

CreateAction creates a new GitHub Pull Request or update an existing one.

func (*PullRequest) EnablePullRequestAutoMerge

func (p *PullRequest) EnablePullRequestAutoMerge(retry int) error

EnablePullRequestAutoMerge updates an existing pullrequest with the flag automerge

func (*PullRequest) GetPullRequestLabelsInformation

func (p *PullRequest) GetPullRequestLabelsInformation(retry int) ([]repositoryLabelApi, error)

getPullRequestLabelsInformation queries GitHub Api to retrieve every labels assigned to a pullRequest

func (*PullRequest) OpenPullRequest

func (p *PullRequest) OpenPullRequest(retry int) error

OpenPullRequest creates a new GitHub Pull Request.

type PullRequestApi

type PullRequestApi struct {
	ChangedFiles int
	BaseRefName  string
	Body         string
	HeadRefName  string
	ID           string
	State        string
	Title        string
	Url          string
	Number       int32
}

PullRequest contains multiple fields mapped to GitHub V4 api

type RateLimit

type RateLimit struct {
	Cost      int
	Remaining int
	ResetAt   string
}

RateLimit is a struct that contains GitHub Api limit information

func (RateLimit) Pause added in v0.109.0

func (a RateLimit) Pause()

Pause pauses the execution if the rate limit is reached until the reset time

func (RateLimit) String added in v0.109.0

func (a RateLimit) String() string

String returns a string representation of the RateLimit struct

type ReleaseNode added in v0.92.0

type ReleaseNode struct {
	Name         string
	TagName      string
	TagCommit    TagCommit
	IsDraft      bool
	IsLatest     bool
	IsPrerelease bool
}

type ReleaseType added in v0.38.0

type ReleaseType struct {
	// "Draft" enable/disable GitHub draft release
	Draft bool
	// "PreRelease" enable/disable GitHub PreRelease
	PreRelease bool
	// "Release" enable/disable GitHub release
	Release bool
	// "Latest" if set to true will only filter the release flag as latest.
	Latest bool
}

ReleaseType specifies accepted GitHub Release type

func (*ReleaseType) Init added in v0.38.0

func (r *ReleaseType) Init()

Init initializes the ReleaseType struct

func (ReleaseType) IsZero added in v0.38.0

func (r ReleaseType) IsZero() bool

IsZero checks if all release type are set to disable

type Repository added in v0.45.0

type Repository struct {
	ID          string
	Name        string
	Owner       string
	ParentID    string
	ParentName  string
	ParentOwner string
	Status      string
}

Repository contains GitHub repository data

type RepositoryRef added in v0.76.1

type RepositoryRef struct {
	ID               string
	HeadOid          string
	DefaultBranchOid string
}

type Spec

type Spec struct {
	// "branch" defines the git branch to work on.
	//
	// compatible:
	//   * scm
	//
	// default:
	//   main
	//
	// remark:
	//   depending on which resource references the GitHub scm, the behavior will be different.
	//
	//   If the scm is linked to a source or a condition (using scmid), the branch will be used to retrieve
	//   file(s) from that branch.
	//
	//   If the scm is linked to target then Updatecli creates a new "working branch" based on the branch value.
	//   The working branch created by Updatecli looks like "updatecli_<pipelineID>".
	//   The working branch can be disabled using the "workingBranch" parameter set to false.
	Branch string `yaml:",omitempty"`
	// WorkingBranchPrefix defines the prefix used to create a working branch.
	//
	// compatible:
	//   * scm
	//
	// default:
	//   updatecli
	//
	// remark:
	//   A working branch is composed of three components:
	//   1. WorkingBranchPrefix
	//   2. Target Branch
	//   3. PipelineID
	//
	//   If WorkingBranchPrefix is set to ”, then
	//   the working branch will look like "<branch>_<pipelineID>".
	WorkingBranchPrefix *string `yaml:",omitempty"`
	// WorkingBranchSeparator defines the separator used to create a working branch.
	//
	// compatible:
	//   * scm
	//
	// default:
	//   "_"
	WorkingBranchSeparator *string `yaml:",omitempty"`
	// "directory" defines the local path where the git repository is cloned.
	//
	// compatible:
	//   * scm
	//
	// remark:
	//   Unless you know what you are doing, it is recommended to use the default value.
	//   The reason is that Updatecli may automatically clean up the directory after a pipeline execution.
	//
	// default:
	//   The default value is based on your local temporary directory like: (on Linux)
	//   /tmp/updatecli/github/<owner>/<repository>
	Directory string `yaml:",omitempty"`
	// "email" defines the email used to commit changes.
	//
	// compatible:
	//   * scm
	//
	// default:
	//   default set to your global git configuration
	Email string `yaml:",omitempty"`
	// "owner" defines the owner of a repository.
	//
	// compatible:
	//   * scm
	Owner string `yaml:",omitempty" jsonschema:"required"`
	// "repository" specifies the name of a repository for a specific owner.
	//
	// compatible:
	//  * scm
	Repository string `yaml:",omitempty" jsonschema:"required"`
	// "token" specifies the credential used to authenticate with GitHub API.
	//
	// compatible:
	//  * scm
	//
	// remark:
	//  A token is a sensitive information, it's recommended to not set this value directly in the configuration file
	//  but to use an environment variable or a SOPS file.
	//
	//  The value can be set to `{{ requiredEnv "GITHUB_TOKEN"}}` to retrieve the token from the environment variable `GITHUB_TOKEN`
	//
	//  or `{{ .github.token }}` to retrieve the token from a SOPS file.
	//  For more information, about a SOPS file, please refer to the following documentation:
	//  https://github.com/getsops/sops
	//
	Token string `yaml:",omitempty"`
	// "url" specifies the default github url in case of GitHub enterprise
	//
	// compatible:
	//   * scm
	//
	// default:
	//   github.com
	//
	URL string `yaml:",omitempty"`
	// "username" specifies the username used to authenticate with GitHub API.
	//
	// compatible:
	//   * scm
	//
	// remark:
	//  the token is usually enough to authenticate with GitHub API. Needed when working with GitHub private repositories.
	Username string `yaml:",omitempty"`
	// "user" specifies the user associated with new git commit messages created by Updatecli
	//
	// compatible:
	//  * scm
	User string `yaml:",omitempty"`
	// "gpg" specifies the GPG key and passphrased used for commit signing
	//
	// compatible:
	//   * scm
	GPG sign.GPGSpec `yaml:",omitempty"`
	// "force" is used during the git push phase to run `git push --force`.
	//
	// compatible:
	//   * scm
	//
	// default:
	//   false
	//
	// remark:
	//   When force is set to true, Updatecli also recreates the working branches that
	//   diverged from their base branch.
	Force *bool `yaml:",omitempty"`
	// "commitMessage" is used to generate the final commit message.
	//
	// compatible:
	//   * scm
	//
	// remark:
	//   it's worth mentioning that the commit message settings is applied to all targets linked to the same scm.
	CommitMessage commit.Commit `yaml:",omitempty"`
	// "submodules" defines if Updatecli should checkout submodules.
	//
	// compatible:
	//   * scm
	//
	// default: true
	Submodules *bool `yaml:",omitempty"`
	// "workingBranch" defines if Updatecli should use a temporary branch to work on.
	// If set to `true`, Updatecli create a temporary branch to work on, based on the branch value.
	//
	// compatible:
	//  * scm
	//
	// default: true
	WorkingBranch *bool `yaml:",omitempty"`
	// "commitUsingApi" defines if Updatecli should use GitHub GraphQL API to create the commit.
	// When set to `true`, a commit created from a GitHub action using the GITHUB_TOKEN will automatically be signed by GitHub.
	// More info on https://github.com/updatecli/updatecli/issues/1914
	//
	// compatible:
	//  * scm
	//
	// default: false
	CommitUsingAPI *bool `yaml:",omitempty"`
	// "app" specifies the GitHub App credentials used to authenticate with GitHub API.
	// It is not compatible with the "token" and "username" fields.
	// It is recommended to use the GitHub App authentication method for better security and granular permissions.
	// For more information, please refer to the following documentation:
	// https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation
	App *app.Spec `yaml:",omitempty"`
}

Spec represents the configuration input

func (*Spec) Merge added in v0.28.0

func (gs *Spec) Merge(child interface{}) error

Merge returns nil if it successfully merges the child Spec into target receiver. Please note that child attributes always overrides receiver's

func (*Spec) MergeFromEnv added in v0.28.0

func (gs *Spec) MergeFromEnv(envPrefix string)

MergeFromEnv updates the target receiver with the "non zero-ed" environment variables

func (*Spec) Validate

func (s *Spec) Validate() (errs []error)

Validate verifies if mandatory GitHub parameters are provided and return false if not.

type TagCommit added in v0.92.0

type TagCommit struct {
	Oid string
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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