> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# sugarshin/gh-pages

Deploy to GitHub Pages


## Commands

### deploy

Deploy assets to GitHub Pages


| Parameter | Type | Default | Description |
|---|---|---|---|
| `branch` | string | gh-pages | Source branch |
| `build-dir` | string | dist | Target directory |
| `commit-message` | string |  | Commit message. default "Built artifacts of ${commit_hash} [ci skip]" |
| `git-email` | string |  | Git email. Default is "${CIRCLE_USERNAME}@users.noreply.github.com"
 |
| `git-host` | string | github.com | Git remote host utl. default github.com |
| `git-user` | string |  | Git username. Default is "${CIRCLE_USERNAME}"
 |
| `reponame-variable` | string | CIRCLE_PROJECT_REPONAME | Project reponame variable. default CIRCLE_PROJECT_REPONAME |
| `setup-git` | boolean | true | Setting Git username and email |
| `ssh-fingerprints` | string |  | Fingerprints for SSH deploy key (add the public key as a read/write key on GitHub; add the private key in CircleCI via SSH Permissions, with github.com as Hostname). Used to push a git tag back to the project's repository.
 |
| `tmp-dir` | string | .deploy | A directory created temporarily for deployment |
| `username-variable` | string | CIRCLE_PROJECT_USERNAME | Project username variable. default CIRCLE_PROJECT_USERNAME |

## Jobs

### deploy

Deploy assets to GitHub Pages


| Parameter | Type | Default | Description |
|---|---|---|---|
| `attach-workspace` | boolean | false | Boolean for whether or not to attach to an existing workspace. Default is false.
 |
| `branch` | string | gh-pages | Source branch |
| `build-dir` | string | dist | Target directory |
| `commit-message` | string |  | Commit message. default "Built artifacts of ${commit_hash} [ci skip]" |
| `executor` | executor | default | Executor |
| `git-email` | string |  | Git email. Default is "${CIRCLE_USERNAME}@users.noreply.github.com"
 |
| `git-user` | string |  | Git username. Default is "${CIRCLE_USERNAME}" |
| `persist-to-workspace` | boolean | false | Boolean for whether or not to persist to a workspace. Default is false
 |
| `reponame-variable` | string | CIRCLE_PROJECT_REPONAME | Project reponame variable. default CIRCLE_PROJECT_REPONAME |
| `ssh-fingerprints` | string |  | Fingerprints for SSH deploy key (add the public key as a read/write key on GitHub; add the private key in CircleCI via SSH Permissions, with github.com as Hostname). Used to push a git tag back to the project's repository.
 |
| `tmp-dir` | string | .deploy | A directory created temporarily for deployment |
| `username-variable` | string | CIRCLE_PROJECT_USERNAME | Project username variable. default CIRCLE_PROJECT_USERNAME |
| `workspace-root` | string | ~/repo | Workspace root path that is either an absolute path or a path relative to the working directory. Defaults to '~/repo'
 |

## Executors

### default

Default executor, with Docker cimg/base


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | stable | Pick a specific circleci/node image variant: https://hub.docker.com/r/cimg/base/tags
 |

## Examples

### deploy-using-command

Example for deploy using command


```yaml
version: '2.1'
orbs:
  gh-pages: sugarshin/gh-pages@x.y.z
jobs:
  build_deploy:
    executor: gh-pages/default
    steps:
      - checkout
      - run: ./build.sh
      - gh-pages/deploy:
          setup-git: true
          ssh-fingerprints: <fingerprint>
workflows:
  Build and Deploy:
    jobs:
      - build_deploy
```

### deploy-using-job

Example for deploy using job


```yaml
version: '2.1'
orbs:
  gh-pages: sugarshin/gh-pages@x.y.z
workflows:
  Build and Deploy:
    jobs:
      - build
      - gh-pages/deploy:
          requires:
            - build
          ssh-fingerprints: <fingerprint>
```