@gradealabs/git-deploy

Git Deploy

A simple module that makes Git deployment easier.

Quick Start

npm install @gradealabs/git-deploy -D

To Use the API:

import gitDeploy from '@gradealabs/git-deploy'
import build from './build'

gitDeploy()
  .use((remote, dir) => build(dir))
  .deploy({
    // The name given to the remote repo deploying to
    name: 'heroku-staging',
    // The branch on the remote repo to deploy to
    branch: 'master',
    // The URL of the remote repo
    url: 'https://git.heroku.com/myapp-staging.git'
  }, 'dist')
  .then(() => console.log('Deployed successfully!'))
  .catch(error => console.error(error))

To Use the CLI:

git-deploy --remote heroku-staging --dir dist --middlewares module/path module/path

CLI

Usage: git-deploy [options]

Options:
--remote, -R   The remote to deploy to.                    [string] [required]
--remotes      Path to JSON file containing an array of remote objects
                                    [string] [default: ".deploy.remotes.json"]
--dir, -D      Path to the folder that should be deployed
                                                    [string] [default: "dist"]
--reset        Determines if the working tree should be reset before the
                middlewares are executed             [boolean] [default: false]
--middlewares  Middleware module IDs to load and register as middleware[array]
--help         Show help                                             [boolean]

Example:

git-deploy --remote heroku-production --dir dist --middlewares deploy-middlware/build

This example will read the .deploy.remotes.json file and attempt to deploy the files in the dist directory to the remote named heroku-production. The .deploy.remotes.json file should look something like this

[
  {
    "name": "heroku-staging",
    "branch": "master",
    "url": "https://git.heroku.com/myapp-staging.git"
  },
  {
    "name": "heroku-production",
    "branch": "master",
    "url": "https://git.heroku.com/myapp-production.git"
  }
]

Optionally the remotes JSON can be provided via STDIN as text. If text is provided as STDIN then the --remotes option will be ignored.

The --middlewares option accepts a list of module IDs to load. Each middleware module is expected to either export a middleware function or an array of middleware functions as it's default export.

See the API documentation for more information on middlware functions.

API

gitDeploy()

Creates a new git deploy builder instance, that is used to add middleware to the deploy process. All middleware is executed asynchronously and sequentially before git push is called.

The GitDeployBuilder has the following interface:

interface GitDeployBuilder {
  use (...middleware: Middleware[]): GitDeployBuilder
  deploy (remote: Remote, dir: string, options?: { reset?: boolean }): Promise<any>
}

interface Middleware {
  (remote: Remote, dir: string, data?: any): Promise<any> | any
}

interface Remote {
  name: string
  branch: string
  url: string
}

Each middlware function is called with the remote object and directory passed to deploy(). They are also called with the result of the previous middlware.

Optionally, you can opt to reset the working tree from the remote branch in the directory being deployed before any middlewares are executed by setting the reset option to true.

Example:

import gitDeploy from '@gradealabs/git-deploy'
// OR import { gitDeploy } from '@gradealabs/git-deploy`
// The module that will build our app for deployment
improt build from './build'

gitDeploy()
  // Add middlware to note the start time
  .use((remote, dir) => ({ start: new Date() }))

  // Add middleware to build the app, ensuring that the result of the
  // previous middleware is passed along for other middleware
  .use((remote, dir, ctx) => build(dir).then(() => ctx))

  .deploy({
    // The name given to the remote repo deploying to
    name: 'heroku-staging',
    // The branch on the remote repo to deploy to
    branch: 'master',
    // The URL of the remote repo
    url: 'https://git.heroku.com/myapp-staging.git'
  }, 'dist', /* The directory to deploy (must not already be a git repo) */
  // Restore/reset the working tree inside 'dist' before executing any
  // middleware functions
  { reset: true })

  // Finally, log the completion message with how much time it took
  .then(ctx => {
    const { start } = ctx
    const finish = new Date()
    const seconds = ((finish - start) / 1000).toFixed(2)
    console.log(`Deploy completed in ${seconds} seconds`)
  })

  .catch(error => console.error(error))

Building

To build the source

npm run build
npm run build:node

To clean all generated folders

npm run clean

Testing

Unit tests are expected to be colocated next to the module/file they are testing and have the following suffix .test.js.

To run unit tests through istanbul and mocha

npm test

Maintainence

To check what modules in node_modules is outdated

npm run audit

To update outdated modules while respecting the semver rules in the package.json

npm update

To update a module to the latest major version (replacing what you have)

npm install themodule@latest -S (if to save in dependencies)
npm install themodule@latest -D (if to save in devDependencies)