Skip to content

Latest commit

 

History

History
814 lines (669 loc) · 21.1 KB

README.md

File metadata and controls

814 lines (669 loc) · 21.1 KB

Froggit-Go

Frogbot

Froggit-Go is a Go library, allowing to perform actions on VCS providers. Currently supported providers are: GitHub, Bitbucket Server , Bitbucket Cloud, Azure Repos and GitLab.

Project status

Scanned by Frogbot Test Coverage Status Mentioned in Awesome Go Go Report Card

Usage

VCS Clients

Create Clients

GitHub

GitHub api v3 is used

// The VCS provider. Cannot be changed.
vcsProvider := vcsutils.GitHub
// API endpoint to GitHub. Leave empty to use the default - https://api.github.com
apiEndpoint := "https://github.example.com"
// Access token to GitHub
token := "secret-github-token"
// Logger
// [Optional]
// Supported logger is a logger that implements the Log interface.
// More information - https://github.com/jfrog/froggit-go/blob/master/vcsclient/logger.go
logger := log.Default()

client, err := vcsclient.NewClientBuilder(vcsProvider).ApiEndpoint(apiEndpoint).Token(token).Build()
GitLab

GitLab api v4 is used.

// The VCS provider. Cannot be changed.
vcsProvider := vcsutils.GitLab
// API endpoint to GitLab. Leave empty to use the default - https://gitlab.com
apiEndpoint := "https://gitlab.example.com"
// Access token to GitLab
token := "secret-gitlab-token"
// Logger
// [Optional]
// Supported logger is a logger that implements the Log interface.
// More information - https://github.com/jfrog/froggit-go/blob/master/vcsclient/logger.go
logger := logger

client, err := vcsclient.NewClientBuilder(vcsProvider).ApiEndpoint(apiEndpoint).Token(token).Build()
Bitbucket Server

Bitbucket api 1.0 is used.

// The VCS provider. Cannot be changed.
vcsProvider := vcsclient.BitbucketServer
// API endpoint to Bitbucket server. Typically ends with /rest.
apiEndpoint := "https://git.acme.com/rest"
// Access token to Bitbucket
token := "secret-bitbucket-token"
// Logger
// [Optional]
// Supported logger is a logger that implements the Log interface.
// More information - https://github.com/jfrog/froggit-go/blob/master/vcsclient/logger.go
logger := log.Default()

client, err := vcsclient.NewClientBuilder(vcsProvider).ApiEndpoint(apiEndpoint).Token(token).Build()
Bitbucket Cloud

Bitbucket cloud api version 2.0 is used and the version should be added to the apiEndpoint.

// The VCS provider. Cannot be changed.
vcsProvider := vcsutils.BitbucketCloud
// API endpoint to Bitbucket cloud. Leave empty to use the default - https://api.bitbucket.org/2.0
apiEndpoint := "https://bitbucket.example.com"
// Bitbucket username
username := "bitbucket-user"
// Password or Bitbucket "App Password'
token := "secret-bitbucket-token"
// Logger
// [Optional]
// Supported logger is a logger that implements the Log interface.
// More information - https://github.com/jfrog/froggit-go/blob/master/vcsclient/logger.go
logger := log.Default()

client, err := vcsclient.NewClientBuilder(vcsProvider).ApiEndpoint(apiEndpoint).Username(username).Token(token).Build()
Azure Repos

Azure DevOps api version v6 is used.

// The VCS provider. Cannot be changed.
vcsProvider := vcsutils.AzureRepos
// API endpoint to Azure Repos. Set the organization.
apiEndpoint := "https://dev.azure.com/<organization>"
// Personal Access Token to Azure DevOps
token := "secret-azure-devops-token"
// Logger
// [Optional]
// Supported logger is a logger that implements the Log interface.
// More information - https://github.com/jfrog/froggit-go/blob/master/vcsclient/logger.go
logger := log.Default()
// Project name
project := "name-of-the-relevant-project"

client, err := vcsclient.NewClientBuilder(vcsProvider).ApiEndpoint(apiEndpoint).Token(token).Project(project).Build()

Test Connection

// Go context
ctx := context.Background()

err := client.TestConnection(ctx)

List Repositories

// Go context
ctx := context.Background()

repositories, err := client.ListRepositories(ctx)

List Branches

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"

repositoryBranches, err := client.ListBranches(ctx, owner, repository)

Download Repository

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Repository branch
branch := "master"
// Local path in the file system
localPath := "/Users/frogger/code/jfrog-cli"

repositoryBranches, err := client.DownloadRepository(ctx, owner, repository, branch, localPath)

Create Webhook

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// The event to watch
webhookEvent := vcsutils.Push
// VCS repository
repository := "jfrog-cli"
// Optional - Webhooks on branches are supported only on GitLab
branch := ""
// The URL to send the payload upon a webhook event
payloadURL := "https://acme.jfrog.io/integration/api/v1/webhook/event"

// token - A token used to validate identity of the incoming webhook.
// In GitHub and Bitbucket server the token verifies the sha256 signature of the payload.
// In GitLab and Bitbucket cloud the token compared to the token received in the incoming payload.
id, token, err := client.CreateWebhook(ctx, owner, repository, branch, "https://jfrog.com", webhookEvent)

Update Webhook

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Optional - Webhooks on branches are supported only on GitLab
branch := ""
// The URL to send the payload upon a webhook event
payloadURL := "https://acme.jfrog.io/integration/api/v1/webhook/event"
// A token to validate identity of the webhook, created by CreateWebhook command
token := "abc123"
// The webhook ID returned by the CreateWebhook API, which created this webhook
webhookID := "123"
// The event to watch
webhookEvent := vcsutils.PrCreated

err := client.UpdateWebhook(ctx, owner, repository, branch, "https://jfrog.com", token, webhookID, webhookEvent)

Delete Webhook

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// The webhook ID returned by the CreateWebhook API, which created this webhook
webhookID := "123"

err := client.DeleteWebhook(ctx, owner, repository, webhookID)

Set Commit Status

// Go context
ctx := context.Background()
// One of Pass, Fail, Error, or InProgress
commitStatus := vcsclient.Pass
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Branch or commit or tag on GitHub and GitLab, commit on Bitbucket
ref := "5c05522fecf8d93a11752ff255c99fcb0f0557cd"
// Title of the commit status
title := "Xray scanning"
// Description of the commit status
description := "Run JFrog Xray scan"
// URL leads to the platform to provide more information, such as Xray scanning results
detailsURL := "https://acme.jfrog.io/ui/xray-scan-results-url"

err := client.SetCommitStatus(ctx, commitStatus, owner, repository, ref, title, description, detailsURL)

Get Commit Status

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Commit tag on GitHub and GitLab, commit on Bitbucket
ref := "5c05522fecf8d93a11752ff255c99fcb0f0557cd"

commitStatuses, err := client.GetCommitStatus(ctx, owner, repository, ref)
Create Pull Request
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Source pull request branch
sourceBranch := "dev"
// Target pull request branch
targetBranch := "main"
// Pull request title
title := "Pull request title"
// Pull request description
description := "Pull request description"

err := client.CreatePullRequest(ctx, owner, repository, sourceBranch, targetBranch, title, description)
Update Pull Request
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Target pull request branch, leave empty for no change.
targetBranch := "main"
// Pull request title
title := "Pull request title"
// Pull request description
body := "Pull request description"
// Pull request ID
id := "1"
// Pull request state
state := vcsutils.Open

err := client.UpdatePullRequest(ctx, owner, repository, title, body, targetBranch, id, state)

List Open Pull Requests With Body

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"

openPullRequests, err := client.ListOpenPullRequestsWithBody(ctx, owner, repository)

List Open Pull Requests

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"

openPullRequests, err := client.ListOpenPullRequests(ctx, owner, repository)

Get Pull Request By ID

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Pull Request ID
pullRequestId := 1

openPullRequests, err := client.GetPullRequestByID(ctx, owner, repository, pullRequestId)
Add Pull Request Comment
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Comment content
content := "Comment content"
// Pull Request ID
pullRequestID := 5

err := client.AddPullRequestComment(ctx, owner, repository, content, pullRequestID)
Add Pull Request Review Comments
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Pull Request ID
pullRequestID := 5
// Pull Request Comment
comments := []PullRequestComment{
  {
    CommentInfo: CommentInfo{
      Content: "content",
    },
    PullRequestDiff: PullRequestDiff{
      OriginalFilePath: index.js   
      OriginalStartLine: 1
      OriginalEndLine: 1
      OriginalStartColumn: 1
      OriginalEndColumn: 1  
      NewFilePath: index.js        
      NewStartLine: 1       
      NewEndLine: 1         
      NewStartColumn: 1     
      NewEndColumn: 1       
    },
  }
}


err := client.AddPullRequestReviewComments(ctx, owner, repository, pullRequestID, comments...)
List Pull Request Comments
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Pull Request ID
pullRequestID := 5

pullRequestComments, err := client.ListPullRequestComment(ctx, owner, repository, pullRequestID)
List Pull Request Review Comments
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Pull Request ID
pullRequestID := 5

pullRequestComments, err := client.ListPullRequestReviewComments(ctx, owner, repository, pullRequestID)
Delete Pull Request Comment
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Pull Request ID
pullRequestID := 5
// Comment ID
commentID := 17

err := client.DeletePullRequestComment(ctx, owner, repository, pullRequestID, commentID)
Delete Pull Request Review Comments
// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Pull Request ID
pullRequestID := 5
// Comment ID
comments := []CommentInfo{
  {
    ID: 2
    // For GitLab
    ThreadID: 7
  }
}

err := client.DeletePullRequestComment(ctx, owner, repository, pullRequestID, comments...)

Get Commits

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// VCS branch
branch := "dev"

// Commits information of the latest branch commits 
commitInfo, err := client.GetCommits(ctx, owner, repository, branch)

Get Commits With Options

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"

// Commits query options 
options := GitCommitsQueryOptions{
  Since: time.Date(2021, 1, 1, 0, 0, 0, 0, time.UTC),
  Until: time.Now(),
  ListOptions: ListOptions{
	  Page:    1,
	  PerPage: 30,
    },
  }

result, err := client.GetCommitsWithQueryOptions(ctx, owner, repository, options)

Get Latest Commit

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// VCS branch
branch := "dev"

// Commit information of the latest commit
commitInfo, err := client.GetLatestCommit(ctx, owner, repository, branch)

Get Commit By SHA

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// SHA-1 hash of the commit
sha := "abcdef0123abcdef4567abcdef8987abcdef6543"

// Commit information of requested commit
commitInfo, err := client.GetCommitBySha(ctx, owner, repository, sha)

Get List of Modified Files

The refBefore...refAfter syntax is used. More about it can be found at Commit Ranges Git documentation.

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// SHA-1 hash of the commit or tag or a branch name
refBefore := "abcdef0123abcdef4567abcdef8987abcdef6543"
// SHA-1 hash of the commit or tag or a branch name
refAfter := "main"

filePaths, err := client.GetModifiedFiles(ctx, owner, repository, refBefore, refAfter)

Add Public SSH Key

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// An identifier for the key
keyName := "my ssh key"
// The public SSH key
publicKey := "ssh-rsa AAAA..."
// Access permission of the key: vcsclient.Read or vcsclient.ReadWrite
permission = vcsclient.Read

// Add a public SSH key to a repository
err := client.AddSshKeyToRepository(ctx, owner, repository, keyName, publicKey, permission)

Get Repository Info

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"

// Get information about repository
repoInfo, err := client.GetRepositoryInfo(ctx, owner, repository)

Get Repository Environment Info

Notice - Get Repository Environment Info is currently supported on GitHub only.

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Environment name
name := "frogbot"

// Get information about repository environment
repoEnvInfo, err := client.GetRepositoryEnvironmentInfo(ctx, owner, repository, name)

Create a label

Notice - Labels are not supported in Bitbucket

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Label info
labelInfo := LabelInfo{
  Name:        "label-name",
  Description: "label description",
  Color:       "4AB548",
}
// Create a label
err := client.CreateLabel(ctx, owner, repository, labelInfo)

Get a label

Notice - Labels are not supported in Bitbucket

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Label name
labelName := "label-name"

// Get a label named "label-name"
labelInfo, err := client.GetLabel(ctx, owner, repository, labelName)

List Pull Request Labels

Notice - Labels are not supported in Bitbucket

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Pull Request ID
pullRequestID := 5

// List all labels assigned to pull request 5
pullRequestLabels, err := client.ListPullRequestLabels(ctx, owner, repository, pullRequestID)

Unlabel Pull Request

Notice - Labels are not supported in Bitbucket

// Go context
ctx := context.Background()
// Organization or username
owner := "jfrog"
// VCS repository
repository := "jfrog-cli"
// Label name
name := "label-name"
// Pull Request ID
pullRequestID := 5

// Remove label "label-name" from pull request 5
err := client.UnlabelPullRequest(ctx, owner, repository, name, pullRequestID)

Upload Code Scanning

Notice - Code Scanning is currently supported on GitHub only.

// Go context
ctx := context.Background()
// The account owner of the git repository
owner := "user"
// The name of the repository
repo := "my_repo"
// The branch name for which the code scanning is relevant
branch := "my_branch"
// A string representing the code scanning results
scanResults := "results"

// Uploads the scanning analysis file to the relevant git provider
sarifID, err := client.UploadCodeScanning(ctx, owner, repo, branch, scanResults)

Download a File From a Repository

Note - This API is currently not supported for Bitbucket Cloud.

// Go context
ctx := context.Background()
// The account owner of the git repository
owner := "user"
// The name of the repository
repo := "my_repo"
// The branch name for which the code scanning is relevant
branch := "my_branch"
// A string representing the file path in the repository
path := "path"

// Downloads a file from a repository
content, statusCode, err := client.DownloadFileFromRepo(ctx, owner, repo, branch, path)

Webhook Parser

// Go context
ctx := context.Background()
// Logger
logger := vcsclient.EmptyLogger{}
// Webhook contextual information
origin := webhookparser.WebhookOrigin{
  // The VCS provider (required)
  VcsProvider: vcsutils.GitHub,
  // Optional URL of the VCS provider (used for building some URLs)
  OriginURL: "https://api.github.com",
  // Token to authenticate incoming webhooks. If empty, signature will not be verified. 
  // The token is a random key generated in the CreateWebhook command. 
  Token: []byte("abc123"),
}
// The HTTP request of the incoming webhook
request := http.Request{}

webhookInfo, err := webhookparser.ParseIncomingWebhook(ctx, logger, origin, request)