jenkins-x/go-scm

Package scm provides a unified interface to multiple source code management systems.

go-scm

A small library with minimal dependencies for working with Webhooks, Commits, Issues, Pull Requests, Comments, Reviews, Teams and more on multiple git provider:

• GitHub
• GitHub Enterprise (you specify a server URL)
• BitBucket Server
• BitBucket Cloud
• GitLab
• Gitea
• Gogs
• Fake
• Azure Devops

Building

See the guide to prerequisites, building and running the code

Working on the code

Clone this repository and use go test...

git clone https://github.com/jenkins-x/go-scm.git
cd go-scm
go test ./...

Writing tests

There are lots of tests for each driver; using sample JSON that comes from the git provider together with the expected canonical JSON.

e.g. I added this test for ListTeams on github: https://github.com/jenkins-x/go-scm/blob/main/scm/driver/github/org_test.go#L83-116

you then add some real json from the git provider: https://github.com/jenkins-x/go-scm/blob/main/scm/driver/github/testdata/teams.json and provide the expected json: https://github.com/jenkins-x/go-scm/blob/main/scm/driver/github/testdata/teams.json.golden

Trying the client on a provider

There are a few little sample programs in scm/factory/examples which are individual binaries you can run from the command line or your IDE.

To test against a git provider of your choice try defining these environment variables:

• GIT_KIND for the kind of git provider (e.g. github, bitbucketserver, gitlab etc)
• GIT_SERVER for the URL of the server to communicate with
• GIT_USER for git user name if using bitbucketclient
• GIT_TOKEN for the git OAuth/private token to talk to the git server

Git API Reference docs

To help hack on the different drivers here's a list of docs which outline the git providers REST APIs

GitHub

• REST API reference: https://developer.github.com/v3/
• WebHooks: https://developer.github.com/v3/activity/events/types/

Bitbucket Server

• REST API reference: https://docs.atlassian.com/bitbucket-server/rest/6.5.1/bitbucket-rest.html
• Webhooks: https://confluence.atlassian.com/bitbucketserver/event-payload-938025882.html

Bitbucket Cloud

• REST API reference: https://developer.atlassian.com/bitbucket/api/2/reference/

Gitlab

• REST API reference: https://docs.gitlab.com/ee/api/

Fake driver for testing

When testing the use of go-scm its really handy to use the fake provider which lets you populate the in memory resources inside the driver or query resources after a test has run.

client, data := fake.NewDefault()

Community

We have a kanban board of stuff to work on if you fancy contributing!

You can also find us on Slack at kubernetes.slack.com:

• #jenkins-x-dev for developers of Jenkins X and related OSS projects
• #jenkins-x-user for users of Jenkins X