GitHub Pages

Commit your site to git and publish it to Github Pages.

See Also: Edit this page


The ghPages Publisher allows you to upload your site to GithubPages.

To use the githubReleases publisher, you'll need to provide Orchid with a githubToken containing a Personal Access Token from Github. Since PATs are confidential and allow anyone who has it complete access to your account, you should set this as an environment variable and add it to your Gradle orchid config from that variable rather than committing it to source control.

orchid {
    githubToken = "${System.getenv('GITHUB_TOKEN')}" 
    // or 'githubToken' in an environment variable without this line

After your PAT is set up, you'll need to set up your repo on GitHub with a gh-pages branch. Orchid will initialize a new local git repo and push it to this branch, overwriting anything currently in that branch.

The username property is the user which issued the PAT, and it is also the organization hosting the repository on GitHub. You can authenticate with a different user than is hosting the repository by setting the repo as username/repo.

Example Usage

 1 services:
 2   publications: 
 3     stages: 
 4       - type: ghPages
 5         username: 'cjbrooks12'
 6         repo: 'JavaEden/Orchid'
 7       #    or
 8       - type: ghPages
 9         username: 'cjbrooks12'
10         repo: '' # becomes cjbrooks12/

API Documentation

Commit your site directly to Github Pages. It can even keep old versions of your site for versioning documentation.

Default Config
# config.yml
        branch: gh-pages
        commitEmail: orchid@orchid
        commitMessage: Deploy to GitHub Pages from Orchid.
        commitUsername: Orchid
        latestDirName: latest
        publishType: CleanBranch
        repo: empty string
        username: empty string
Key Type Default Value Description
branch String gh-pages

The branch to push to.

commitEmail String orchid@orchid

The email on the commit.

commitMessage String Deploy to GitHub Pages from Orchid.

The commit message to attach to this deploy.

commitUsername String Orchid

The username on the commit.

githubUrl String

The URL for a self-hosted Github Enterprise installation.

latestDirName String latest

The name of the 'latest' directory used for the VersionedBranchWithLatest publish type.

publishType PublishType CleanBranch

The type of publication to use for Github Pages.

  • CleanBranch: Create a new branch with no history and force-push to the remote. Overwrites existing branch completely.
  • CleanBranchMaintainHistory: Clone existing branch, remove all files, then push to the remote. Overwrites all files, but maintains history.
  • VersionedBranch: Clone existing branch, add current site to a versioned subfolder, then push to the remote. Maintains history and all prior versions' content.
  • VersionedBranchWithLatest: Clone existing branch, add current site to a 'latest' and a versioned subfolder, then force-push to the remote. Maintains history and all prior versions' content.
repo String empty string

The repository to push to, as [username/repo], or just [repo] to use the authenticating username.

username String empty string

The user or organization with push access to your repo, used for authenticating with GitHub.

Key Type Default Value Description
allData Map<String, Object> {}

All options passed to this object.

dry boolean false
order int 0

Manually set the order in which this publisher executes

Key Type Description
allPublishers Site Config

Configure this item with additional options merged in from config.yml, from the object at the archetype key. Dots in the key indicate sub-objects within the site config.