Deploy Pages

Deploy provider for github pages

Deploys build files to github pages, requires git >= 2.7.4.

• Install
• Deployment
  • Github Pages
    • Considerations
    • Remote Repository
    • Recipes
      • User / Organization Recipes
      • Project Recipes
    • Deploy Tags
    • Repository Validation
    • Deployment Process
    • Deployment Notes
• API
  • GithubPagesProvider
    • See Also
    • .validate
    • .tag
    • .deploy
• License

Install

yarn add makestatic-deploy-pages

Deployment

There are some decisions that need to be made when deploying to github pages this section will look at them in detail.

Github Pages

The general syntax for deploying to github pages is as follows:

module.exports {
  deploy: {
    // deployments are configured per environment
    stage: {
      // deployment provider for github pages
      pages: {
        // configure the github pages flavour
        // one of `org`, `user` or `project`, default is `org`
        type: 'project',
        // name of the git remote to use for push, default is `deploy`
        remote: 'origin',
        // name of the remote branch to push to, default is `master`
        branch: 'gh-pages',
        // indicate whether the build files are untracked, default is `false`
        ignored: true
      }
    }
  }
}

You can then clean, build and deploy with:

makestatic --env stage --provider pages

Considerations

The questions that you need to answer before configuring a github pages deployment are:

• Am I deploying the site for a user (or organization) or a project?
• Do I want to ignore the build files from the git working tree?

The answers to these questions will determine how you configure the deployment and any steps you may need to take in the github interface.

If you wish to deploy to the user or organization flavour the important thing to remember is that the files must be served from the master branch, if the deployment is for the project style of github pages then the files can be served from the master or gh-pages branches or from a /docs directory -- in which case you need to configure this for the deployment.

If you want to commit the build files to your working tree it will speed up deployment as git will only push files that have changed however in some situations this is not ideal. For example if your production deployment goes to a different provider and you want to deploy to github pages for the stage environment it may be preferable to ignore the build files from the working tree.

A small but important detail is that if you are deploying to user or organization pages the site is served from {user-or-org}.github.io which makes it safe to use absolute file paths like /style.css in your web site however if you are deploying to project pages the site will be served from {user-or-org}.github.io/{project} in which case you should not use absolute path references or you will find that files are not found when the site is deployed.

Remote Repository

It is recommended that you set up a remote specific for deployment which will make it easier to switch to another repository later. If you use the default remote name of deploy there is no additional configuration required.

git remote add deploy \
  [email protected]:makestatic/makestatic.github.io.git

Be sure to change the remote repository URL to match your setup.

Recipes

Before going into detail on the deployment logic here are some configuration recipes for the available deployment styles.

There are some repositories that are configured to verify these deployments you may want to take a look at them.

• Deploy Github Pages Org
• Deploy Github Pages Org w/ Untracked Files
• Deploy Github Pages Project
• Deploy Github Pages Project w/ Untracked Files

User / Organization Recipes

Note that using user or org for the deployment type is effectively the same.

If your build files are checked in to the working tree.

module.exports = {
  deploy: {
    stage: {
      pages: {
        type: 'org'
      }
    }
  }
}

If they are being ignored, set the ignored flag:

module.exports = {
  deploy: {
    stage: {
      pages: {
        type: 'org',
        ignored: true
      }
    }
  }
}

Project Recipes

If you are deploying using project style pages set the type to project and configure the remote branch to push to:

module.exports = {
  deploy: {
    stage: {
      pages: {
        type: 'project',
        branch: 'gh-pages'
      }
    }
  }
}

In this case the remote branch can be either gh-pages or master but must match what you have configured in the repository settings when you enabled github project pages.

If you want to use the /docs directory to serve the web site from you should configure the build to write to the docs directory:

module.exports = {
  output: 'docs',
  deploy: {
    stage: {
      pages: {
        type: 'project'
      }
    }
  }
}

Deploy Tags

Each deployment must have a unique tag. By default this will be created using a convention but you can override this logic if necessary.

The convention is to load package.json from the current working directory and prefix the package version with deploy-v such that if your application has a 1.0.0 version the deployment tag is set to deploy-v1.0.0.

If you want to implement your own logic for generating a unique deployment tag you can assign a tag function to the provider:

module.exports = {
  deploy: {
    stage: {
      pages: {
        tag: () => {
          // generate and return a unique tag name for the deployment
        }
      }
    }
  }
}

Repository Validation

Before deployment the provider will check that your local repository is safe to work with which means the following requirements are necessary to perform a deployment using git:

• Repository working tree may not be dirty
• Repository working tree may not contain untracked files
• Repository branch list cannot contain the deploy tag
• Repository tag list cannot contain the deploy tag
• Configured remote (eg: deploy) must exist

Deployment Process

The deployment process is the same for all types of pages deployment with slight variations in how files are pushed. This section gives an overview of the common steps.

Before pushing files the deployment provider will:

• Perform validation to determine that it is safe to deploy
• Checkout a temporary branch based on the deploy tag
• If the build files are ignored they are added to the temporary branch

Then the push to the remote will execute which will vary slightly based on the deployment configuration.

Subsequently the following steps are taken:

• Switch back to the original branch
• Delete the temporary deploy branch
• Create a tag using the deployment tag

At this point the deployment is complete and you have a tag that can be used to revert to an earlier deployment if necessary.

Deployment Notes

Once you have a remote set up you can configure the deployment in this case we assume configuration for the stage environment. In your app.stage.js file set the name of the remote to use, indicate which flavour of github pages you are using by setting the type and whether the build directory is being ignored:

module.exports = {
  deploy: {
    stage: {
      pages: {
        type: 'org',
        ignored: true
      }
    }
  }
}

The type may be either org or user (which are equivalent) or project. The ignored property indicates whether the build files are being ignored from the working directory which impacts the logic used for deployment.

Because in this configuration we have set the type to org configuring a remote branch would have no effect as the deployment must go to the master branch as that is where your web site will be served from.

This type of configuration potentially requires you to modify the github settings for the repository. Because the files are being ignored and they are in a sub-folder (the public directory by default) we need to push them to the root of the master branch. The deployment logic handles this scenario but there is one caveat, when the build files are being ignored to push to master when master already exists we need to delete the remote master branch before pushing the updated build files. In order to do this the master branch must not be configured as the default branch for the repository.

If you are creating a new repository and perform a deployment for this configuration then there is nothing you need to do as the deployment will push a branch other than master first which then becomes the default branch allowing master to be deleted when pushing new deployments. However if you already have a master branch and it is the default branch you need to change the default branch, go to the repository Settings > Branches and select a branch other than master as the default branch then you will be able to use this style of deployment configuration.

API

GithubPagesProvider

Deploys the site to github pages.

See Also

• Deploy Site

.validate

GithubPagesProvider.prototype.validate(info)

Validates that the working directory is safe for a deployment.

It is also responsible for propagating the info argument with useful information such as the list of tags and branches and the current branch.

Returns a promise that resolves once all validations pass.

• info Object deployment configuration information.

.tag

GithubPagesProvider.prototype.tag()

Default implementation for getting a deployment tag.

Requires package.json in the current working directory, extracts the package version and prepends a deploy-v prefix.

Returns deployment tag.

.deploy

GithubPagesProvider.prototype.deploy(context, config)

Perform the deployment.

This is the function that is called by the deploy-site plugin.

Returns a promise that resolves once deployment is complete.

• context Object the processing context.
• config Object the deployment configuration.

License

MIT

Created by mkdoc on March 12, 2017