Git client
SDK to interact with different git servers using a consistent api.
CLI installation
To install the latest version of gitu into /usr/local/bin
, run the following:
curl -sL https://gitu.cloudnativetoolkit.dev/install.sh | sh
If you would like to install the CLI in a different directory, use the following:
curl -sL https://gitu.cloudnativetoolkit.dev/install.sh | DEST_DIR=~/bin sh
Usage
The SDK will determine the type of repo given the url to the server and return a GitApi
instance that implements the apis for that server. The url can point to a specific repository or to an organization.
The api can be loaded using the apiFromUrl
helper function:
import {apiFromUrl} from 'git-client'
const api: GitApi = apiFromUrl('https://github.com/org/repo', {username, password})
From there, any of the implemented apis can be called. For example:
api.createWebhook({webhookUrl: 'https://webhook'})
Provided CLI commands
create
Creates a git repo from the provided information
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu create my-repo -h github.com
To create the repo in a different org, include the -o
flag
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu create my-repo -h github.com -o myorg
exists
Checks if a given repo exists and return some information about it.
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu exists https://github.com/myuser/my-repo
or you can check for the repo using the parts of the url
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu exists my-repo -h github.com
delete
Deletes the provided repo
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu delete https://github.com/myuser/my-repo
or you can delete the repo using the parts of the url
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu delete my-repo -h github.com
clone
Clones the repository, handling the credentials and the name and email config
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu clone https://github.com/myuser/my-repo
or you can clone the repo using the parts of the url
export GIT_USERNAME="myuser"
export GIT_TOKEN="xxx"
gitu clone my-repo -h github.com
Provided APIs
The exposed APIs are defined in lib/git.api.ts
in the GitApi
abstract class. The available API functions are:
-
createRepo()
- creates a repository in the org -
deleteRepo()
- deletes the repository -
getWebhooks()
- list the defined webhooks -
createWebhook()
- create a webhook on the repository -
deleteBranch()
- deletes a branch in the repository -
rebaseBranch()
- rebases a branch on top of another one in the repository -
getPullRequest()
- retrieves a pull request from the repository -
createPullRequest()
- creates a pull request in the repository for a given branch -
mergePullRequest()
- merges the given pull request -
updateAndMergePullRequest()
- updates the pull request with the latest from the target branch and merges it -
updatePullRequestBranch()
- updates the pull request with the latest from the target branch -
clone()
- clones the repository to the local file system
Command-line credentials
Credentials can be provided to the command-line for each command using the -u
and --token
argument OR the credentials can be stored in a configuration file for each host.
The configuration file is named .gitu-config
and should be stored in the home directory. Each entry should contain the host
, username
and token
. Optionally, if the git server uses a self-signed certificate it can also be provided to the configuration with the caCert
value.
For example:
credentials:
- host: github.com
username: myuser
token: token
- host: git.myhost.com
username: githuser
token: token
caCert: /path/to/ca.crt
Testing
The repository provides unit tests and integration tests. The unit tests can be run independently of any Git hosts. The integration tests require configuration, including credentials, in order to run.
Unit tests
To execute the unit tests, run the following:
npm test
Integration tests
The integration test runner will execute any files that match the pattern *.ispec.ts
. To run the integration tests:
-
Copy
.env.template
to.env
and provide values for the environment variables for the repositories you want to test. If environment variables are missing for a type of repository then it will be skipped (or you can skip testing a type of repository by setting XXX_SKIP="true") -
Run the following command:
npm run test:integration
Note: The integration tests will create a repository, execute some APIs, then delete the repository. The Personal Access Token provided for the XXX_PASSWORD
environment variable needs to have enough permission to delete the repo.
Notes
- clone {url} [{path}] (include name and email config)
- pr create
- pr merge
- pr get