README.md

Froggit-Go

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

Usage

• Froggit-Go
  • Project status
  • Usage
    • VCS Clients
      • Create Clients
        • GitHub
        • GitLab
        • Bitbucket Server
        • Bitbucket Cloud
        • Azure Repos
      • Test Connection
      • List Repositories
      • List Branches
      • Download Repository
      • Create Webhook
      • Update Webhook
      • Delete Webhook
      • Set Commit Status
      • Get Commit Status
      • Create Pull Request
      • Update Pull Request
      • Get Pull Request By ID
      • List Open Pull Requests
      • List Open Pull Requests With Body
      • Add Pull Request Comment
      • Add Pull Request Review Comments
      • List Pull Request Comments
      • List Pull Request Review Comments
      • Delete Pull Request Comment
      • Delete Pull Request Review Comments
      • Get Commits
      • Get Commits With Options
      • Get Latest Commit
      • Get Commit By SHA
      • Get List of Modified Files
      • Add Public SSH Key
      • Get Repository Info
      • Get Repository Environment Info
      • Create a label
      • Get a label
      • List Pull Request Labels
      • Unlabel Pull Request
      • Upload Code Scanning
      • Download a File From a Repository
    • Webhook Parser

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)