deploy-to-github-pages
Version:
A Node library that makes deploying a directory on a branch to GitHub pages easy and automatic.
79 lines (55 loc) • 4.05 kB
Markdown
# :rocket: deploy-to-github-pages
[](https://www.npmjs.com/package/deploy-to-github-pages)
[](https://github.com/oliverviljamaa/deploy-to-github-pages/releases)
[](https://circleci.com/gh/oliverviljamaa/deploy-to-github-pages)
[](https://github.com/oliverviljamaa/deploy-to-github-pages/blob/master/LICENSE)
A Node and CLI tool that makes deploying to GitHub pages **by branch** easy and automatic, best used as part of a CI process.
On `master` (or on your specified `defaultBranch` or `-m`) your directory will be deployed to your GitHub page root similarly to other libraries, such as the wonderful [`gh-pages`](https://www.npmjs.com/package/gh-pages).
On other branches, it'll be deployed under `/branch/${branchName}`, allowing your peers to QA your built docs/demos easily for better feedback.
It also sends a status to a Pull request, if one exists:
<img src="https://user-images.githubusercontent.com/5443561/37659087-e9f1cc14-2c46-11e8-82cf-1e76750d0e3f.gif" width="480">
## Installation
```bash
npm install -D deploy-to-github-pages
```
## Usage
### CLI
```bash
deploy-to-github-pages [...options]
```
### Node
```javascript
const deploy = require('deploy-to-github-pages');
deploy(options).catch(err => {
console.log(err);
});
```
### Options
| Option | flag | description | default | env variable | required | required in CI |
| --------------- | ---: | -------------------------------------------------- | ---------- | -------------- | -------: | -------------: |
| `directory` | -d | directory you wish to deploy | `'public'` | | \* | \* |
| `token` | -t | [GitHub token](https://github.com/settings/tokens) | | `GITHUB_TOKEN` | \* | \* |
| `owner` | -o | GitHub repo owner/org | | | \* | |
| `repo` | -r | GitHub repo name | | | \* | |
| `branch` | -b | branch name | `'master'` | | \* | |
| `buildUrl` | -u | link displayed when deployment fails | | | | |
| `defaultBranch` | -m | Your GitHub default branch | `'master'` | | | |
Therefore, if ran from CircleCI or GitHub Actions workflows with a `GITHUB_TOKEN` environment variable present and the directory to be deployed is named `public`, _no configuration options are needed_, so just the following is enough:
```bash
deploy-to-github-pages
```
or
```javascript
deploy().catch(err => {
console.log(err);
});
```
## Contributing
1. Run tests with `yarn test`.
1. Develop.
1. **Bump version number in `package.json` according to [semver](http://semver.org/) and add an item that a release will be based on to `CHANGELOG.md`**.
1. Submit your pull request from a feature branch and get code reviewed.
1. If the pull request is approved and the [CircleCI build](https://circleci.com/gh/oliverviljamaa/deploy-to-github-pages) passes, you will be able to squash and merge.
1. Code will automatically be released to [GitHub](https://github.com/oliverviljamaa/deploy-to-github-pages/releases) and published to [npm](https://www.npmjs.com/package/deploy-to-github-pages) according to the version specified in the changelog and `package.json`.
## Other
For features and bugs, feel free to [add issues](https://github.com/oliverviljamaa/deploy-to-github-pages/issues) or contribute.