resource

package module
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: Jun 18, 2018 License: MIT Imports: 18 Imported by: 0

README

Github PR resource

Build Status Go Report Card Docker Automated build

A Concourse resource for pull requests on Github. Written in Go and based on the Github V4 (GraphQL) API. Inspired by the original, with some important differences:

  • Github V4: check only requires 1 API call per 100th open pull request. (See #costs for more information).
  • Fetch/merge: get will always merge a specific commit from the Pull request into the latest base.
  • Metadata: get and put provides information about which commit (SHA) was used from both the PR and base.
  • Webhooks: Does not implement any caching thanks to GraphQL, which means it works well with webhooks.

Source Configuration

Parameter Required Example Description
repository Yes itsdalmo/test-repository The repository to target.
access_token Yes A Github Access Token with repository access (required for setting status on commits).
v3_endpoint No https://api.github.com Endpoint to use for the V3 Github API (Restful).
v4_endpoint No https://api.github.com/graphql Endpoint to use for the V4 Github API (Graphql).
paths No terraform/**/*.tf Only produce new versions if the PR includes changes to files that match one or more glob pattern.
ignore_paths No .ci/* Inverse of the above. Pattern syntax is documented in filepath.Match.
disable_ci_skip No true (string) Disable ability to skip builds with [ci skip] and [skip ci] in commit message or pull request title.

Note: If v3_endpoint is set, v4_endpoint must also be set (and the other way around).

Behaviour

check

Produces new versions for all commits (after the last version) ordered by the committed date. A version is represented as follows:

  • pr: The pull request number.
  • commit: The commit SHA.
  • committed: Timestamp of when the commit was committed. Used to filter subsequent checks.

If several commits are pushed to a given PR at the same time, the last commit will be the new version.

Note on webhooks: This resource does not implement any caching, so it should work well with webhooks (should be subscribed to push events). One thing to keep in mind however, is that pull requests that are opened from a fork and commits to said fork will not generate notifications over the webhook. So if you have a repository with little traffic and expect pull requests from forks, you'll need to discover those versions with check_every: 1m for instance. check in this resource is not a costly operation, so normally you should not have to worry about the rate limit.

get

Clones the base (e.g. master branch) at the latest commit, and merges the pull request at the specified commit into master. This ensures that we are both testing and setting status on the exact commit that was requested in input. Because the base of the PR is not locked to a specific commit in versions emitted from check, a fresh get will always use the latest commit in master and report the SHA of said commit in the metadata.

Note that, should you retrigger a build in the hopes of testing the last commit to a PR against a newer version of the base, Concourse will reuse the volume (i.e. not trigger a new get) if it still exists, which can produce unexpected results (#5). As such, re-testing a PR against a newer version of the base is best done by pushing an empty commit to the PR.

put
Parameter Required Example Description
path Yes pull-request The name given to the resource in a GET step.
status No SUCCESS Set a status on a commit. One of SUCCESS, PENDING, FAILURE and ERROR.
context No unit-test A context to use for the status. (Prefixed with concourse-ci, defaults to concourse-ci/status).
comment No hello world! A comment to add to the pull request.
comment_file No my-output/comment.txt Path to file containing a comment to add to the pull request (e.g. output of terraform plan).

Example

resource_types:
- name: pull-request
  type: docker-image
  source:
    repository: teliaoss/github-pr-resource

resources:
- name: pull-request
  type: pull-request
  check_every: 24h
  webhook_token: ((webhook-token))
  source:
    repository: itsdalmo/test-repository
    access_token: ((github-access-token))

jobs:
- name: test
  plan:
  - get: pull-request
    trigger: true
    version: every
  - put: pull-request
    params:
      path: pull-request
      status: pending
  - task: unit-test
    config:
      platform: linux
      image_resource:
        type: docker-image
        source: {repository: alpine/git, tag: "latest"}
      inputs:
        - name: pull-request
      run:
        path: /bin/sh
        args:
          - -xce
          - |
            cd pull-request
            git log --graph --all --color --pretty=format:"%x1b[31m%h%x09%x1b[32m%d%x1b[0m%x20%s" > log.txt
            cat log.txt
    on_failure:
      put: pull-request
      params:
        path: pull-request
        status: failure
  - put: pull-request
    params:
      path: pull-request
      status: success

Costs

The Github API(s) have a rate limit of 5000 requests per hour (per user). This resource will incur the following costs:

  • check: Minimum 1, max 1 per 100th open pull request.
  • in: Fixed cost of 1. Fetches the pull request at the given commit.
  • out: Minimum 1, max 3 (1 for each of status, comment and comment_file).

E.g., typical use for a repository with 125 open pull requests will incur the following costs for every commit:

  • check: 2 (paginate 125 PR's with 100 per page)
  • in: 1 (fetch the pull request at the given commit ref)
  • out: 1 (set status on the commit)

With a rate limit of 5000 per hour, it could handle 1250 commits between all of the 125 open pull requests in the span of that hour.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContainsSkipCI 

func ContainsSkipCI(s string) bool

ContainsSkipCI returns true if a string contains [ci skip] or [skip ci].

func FilterIgnorePath 

func FilterIgnorePath(files []string, pattern string) ([]string, error)

FilterIgnorePath ...

func FilterPath 

func FilterPath(files []string, pattern string) ([]string, error)

FilterPath ...

Types

type CheckRequest 

type CheckRequest struct {
	Source  Source  `json:"source"`
	Version Version `json:"version"`
}

CheckRequest ...

type CheckResponse 

type CheckResponse []Version

CheckResponse ...

func Check 

func Check(request CheckRequest, manager Github) (CheckResponse, error)

Check (business logic)

func (CheckResponse) Len 

func (r CheckResponse) Len() int

func (CheckResponse) Less 

func (r CheckResponse) Less(i, j int) bool

func (CheckResponse) Swap 

func (r CheckResponse) Swap(i, j int)

type CommitObject 

type CommitObject struct {
	ID            string
	OID           string
	CommittedDate githubv4.DateTime
	Message       string
	Author        struct {
		User struct {
			Login string
		}
	}
}

CommitObject represents the GraphQL commit node. https://developer.github.com/v4/object/commit/

type GetParameters 

type GetParameters struct{}

GetParameters ...

type GetRequest 

type GetRequest struct {
	Source  Source        `json:"source"`
	Version Version       `json:"version"`
	Params  GetParameters `json:"params"`
}

GetRequest ...

type GetResponse 

type GetResponse struct {
	Version  Version  `json:"version"`
	Metadata Metadata `json:"metadata,omitempty"`
}

GetResponse ...

func Get 

func Get(request GetRequest, github Github, git Git, outputDir string) (*GetResponse, error)

Get (business logic)

type Git 

type Git interface {
	Init() error
	Pull(string) error
	Fetch(string, int) error
	Checkout(string) error
	Merge(string) error
	RevParse(string) (string, error)
}

Git interface for testing purposes.

type GitClient 

type GitClient struct {
	AccessToken string
	Directory   string
	Output      io.Writer
}

GitClient ...

func NewGitClient 

func NewGitClient(source *Source, dir string, output io.Writer) (*GitClient, error)

NewGitClient ...

func (*GitClient) Checkout 

func (g *GitClient) Checkout(name string) error

Checkout ...

func (*GitClient) Endpoint 

func (g *GitClient) Endpoint(uri string) (string, error)

Endpoint takes an uri and produces an endpoint with the login information baked in.

func (*GitClient) Fetch 

func (g *GitClient) Fetch(uri string, prNumber int) error

Fetch ...

func (*GitClient) Init 

func (g *GitClient) Init() error

Init ...

func (*GitClient) Merge 

func (g *GitClient) Merge(sha string) error

Merge ...

func (*GitClient) Pull 

func (g *GitClient) Pull(uri string) error

Pull ...

func (*GitClient) RevParse 

func (g *GitClient) RevParse(branch string) (string, error)

RevParse retrieves the SHA of the given branch.

type Github 

type Github interface {
	ListOpenPullRequests() ([]*PullRequest, error)
	ListModifiedFiles(int) ([]string, error)
	PostComment(string, string) error
	GetPullRequest(string, string) (*PullRequest, error)
	UpdateCommitStatus(string, string, string) error
}

Github for testing purposes.

type GithubClient 

type GithubClient struct {
	V3         *github.Client
	V4         *githubv4.Client
	Repository string
	Owner      string
}

GithubClient for handling requests to the Github V3 and V4 APIs.

func NewGithubClient 

func NewGithubClient(s *Source) (*GithubClient, error)

NewGithubClient ...

func (*GithubClient) GetPullRequest added in v0.5.0 

func (m *GithubClient) GetPullRequest(prNumber, commitRef string) (*PullRequest, error)

GetPullRequest ...

func (*GithubClient) ListModifiedFiles 

func (m *GithubClient) ListModifiedFiles(prNumber int) ([]string, error)

ListModifiedFiles in a pull request (not supported by V4 API).

func (*GithubClient) ListOpenPullRequests 

func (m *GithubClient) ListOpenPullRequests() ([]*PullRequest, error)

ListOpenPullRequests gets the last commit on all open pull requests.

func (*GithubClient) PostComment 

func (m *GithubClient) PostComment(prNumber, comment string) error

PostComment to a pull request or issue.

func (*GithubClient) UpdateCommitStatus 

func (m *GithubClient) UpdateCommitStatus(commitRef, statusContext, status string) error

UpdateCommitStatus for a given commit (not supported by V4 API).

type Metadata 

type Metadata []*MetadataField

Metadata output from get/put steps.

func (*Metadata) Add 

func (m *Metadata) Add(name, value string)

Add a MetadataField to the Metadata.

type MetadataField 

type MetadataField struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

MetadataField ...

type PullRequest 

type PullRequest struct {
	PullRequestObject
	Tip CommitObject
}

PullRequest represents a pull request and includes the tip (commit).

type PullRequestObject 

type PullRequestObject struct {
	ID          string
	Number      int
	Title       string
	URL         string
	BaseRefName string
	HeadRefName string
	Repository  struct {
		URL string
	}
}

PullRequestObject represents the GraphQL commit node. https://developer.github.com/v4/object/commit/

type PutParameters 

type PutParameters struct {
	Path        string `json:"path"`
	Context     string `json:"context"`
	Status      string `json:"status"`
	CommentFile string `json:"comment_file"`
	Comment     string `json:"comment"`
}

PutParameters for the resource.

func (*PutParameters) Validate 

func (p *PutParameters) Validate() error

Validate the put parameters.

type PutRequest 

type PutRequest struct {
	Source Source        `json:"source"`
	Params PutParameters `json:"params"`
}

PutRequest ...

type PutResponse 

type PutResponse struct {
	Version  Version  `json:"version"`
	Metadata Metadata `json:"metadata,omitempty"`
}

PutResponse ...

func Put 

func Put(request PutRequest, manager Github, inputDir string) (*PutResponse, error)

Put (business logic)

type Source 

type Source struct {
	Repository    string   `json:"repository"`
	AccessToken   string   `json:"access_token"`
	V3Endpoint    string   `json:"v3_endpoint"`
	V4Endpoint    string   `json:"v4_endpoint"`
	Paths         []string `json:"path"`
	IgnorePaths   []string `json:"ignore_path"`
	DisableCISkip string   `json:"disable_ci_skip"`
}

Source represents the configuration for the resource.

func (*Source) Validate 

func (s *Source) Validate() error

Validate the source configuration.

type Version 

type Version struct {
	PR            string    `json:"pr"`
	Commit        string    `json:"commit"`
	CommittedDate time.Time `json:"committed,omitempty"`
}

Version communicated with Concourse. ID is the Github Global ID.

func NewVersion 

func NewVersion(p *PullRequest) Version

NewVersion constructs a new Version.

Source Files

View all Source files

Directories

Path Synopsis
cmd
check
in
out
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

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.