Publishing

The following sections show you how to configure publishing of your site. To publish a generated site to GitHub Pages you can use the sbt-ghpages plugin. For sites hosted on S3 one option is to use sbt-s3. We expect other publishing mechanisms to be supported in the future.

Publishing to GitHub Pages using sbt-ghpages

Set up the plugin by adding the following to project/plugins.sbt (check the sbt-ghpages project for the most recent version).

copysourceaddSbtPlugin(
  ("com.github.sbt" % "sbt-ghpages" % "0.7.0")
    // sbt-ghpages depends on sbt-site 1.4.1, which pulls Scala XML 1.x
    .exclude("org.scala-lang.modules", "scala-xml_2.12")
)

Then configure your sbt build to use a special remote when running on Travis CI and otherwise fall back to the normal Git remote configured via the scmInfo setting.

copysourcescmInfo := Some(ScmInfo(url("https://github.com/sbt/sbt-site"), "scm:git:[email protected]:sbt/sbt-site.git")),
enablePlugins(GhpagesPlugin)
git.remoteRepo := scmInfo.value.get.connection.replace("scm:git:", "")

At this point you should be able to run sbt ghpagesPushSite to publish your site.

$ sbt clean make-site                             # <1> Build the site
$ origin=$(git remote get-url origin)             # <2> Save the current remote for later
$ cd target/site
$ git init                                        # <3> Create site repo and add initial content
$ git add .
$ git commit -m "Initial import of GitHub Pages"
$ git push --force "$origin" master:gh-pages      # <4> Publish the repo's master branch as gh-pages

Publishing to GitHub Pages from Travis CI

The following section walks you through the steps to configure Travis CI to publish your site as part of the deployment process. It assumes that you have already configured your sbt project to publish your site using the sbt-ghpages plugin as described in the previous section.

To authenticate Travis CI to publish changes to the gh-pages branch you need to first generate an SSH key pair:

$ ssh-keygen -t rsa -b 4096 -C "sbt-site@travis" -f project/travis-deploy-key

Add the public key found in project/travis-deploy-key.pub as a deploy key in the Deploy Keys section of your GitHub project’s settings page at https://github.com/[org]/[repo]/settings/keys. Make sure you allow write access for the deploy key by clicking the check box.

Prepare the secret key for inclusion in the repository by opening a terminal and encrypting the secret key file using the Travis CLI:

$ gem install travis
$ travis encrypt-file project/travis-deploy-key project/travis-deploy-key.enc
encrypting project/travis-deploy-key for [org]/[repo]
storing result as project/travis-deploy-key.enc
storing secure env variables for decryption

Please add the following to your build script (before_install stage in your .travis.yml, for instance):

    openssl aes-256-cbc -K $encrypted_3afbfedfa397_key -iv $encrypted_3afbfedfa397_iv -in project/travis-deploy-key.enc -out project/travis-deploy-key -d

Pro Tip: You can add it automatically by running with --add.

Make sure to add project/travis-deploy-key.enc to the git repository.
Make sure not to add project/travis-deploy-key to the git repository.
Commit all changes to your .travis.yml.

As instructed in the output of the command add the encrypted secret key found in project/travis-deploy-key.enc to the repository and delete or ignore the unencrypted secret key file.

$ git add project/travis-deploy-key.enc
$ echo project/travis-deploy-key >> .git/info/exclude

Finally, configure a deploy step in .travis.yml using the script provider. For a complete set of options and triggers see the Travis deployment documentation. In this example, we publishing when a tag is created and explicitly disable publishing for pull request. The before_deploy step takes care of setting up the environment so that git push automatically finds the deploy key.

copysourcebefore_deploy:
  # Record minimal build information via the Git user ident
  - git config --global user.name "$USER"
  - git config --global user.email "$TRAVIS_BUILD_NUMBER@$TRAVIS_COMMIT"
  # Decrypt the secret deploy key using instructions from `travis encrypt-file`
  - openssl aes-256-cbc -K $encrypted_3afbfedfa397_key -iv $encrypted_3afbfedfa397_iv -in project/travis-deploy-key.enc -out project/travis-deploy-key -d
  - chmod 600 project/travis-deploy-key
  # Start ssh-agent in the background and load the deploy key
  - eval "$(ssh-agent -s)"
  - ssh-add project/travis-deploy-key

deploy:
  provider: script
  script: sbt ghpagesPushSite
  skip_cleanup: true
  on:
    tags: true
    condition: $TRAVIS_PULL_REQUEST = false && $SBT_CROSS_VERSION = 1.1*