@cloudnativetoolkit/git-client NPM

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.