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).

sourceaddSbtPlugin(
  ("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.

sourcescmInfo := 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.

Note

Before running sbt ghpagesPushSite the first time you need to create the gh-pages branch. One way to do it is to build your site and publish a first version of it using the following commands:

$ 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.

Security Considerations

The authentication mechanism that enables Travis CI to update the gh-pages branch requires that write access to your GitHub project is granted to an SSH key pair that you control. An encrypted version of the secret key must be added to the Git repository in order for Travis CI to decrypt it and make it available for pushing to your Git repository. This means that anyone with the ability to modify the Travis CI or sbt build configuration will be able to get hold of the secret key and gain write access to your GitHub repository. For this reason it is recommented to disable publishing for pull requests.

The instructions are based on this gist and you are encouraged to consult the reasons for choosing this authentication mechanism.

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.

Add the Travis SSH Deploy Key

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.

sourcebefore_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*
Note

Ensure that you modify the above example to use the instructions on how to decrypt the deploy key provided in the output of the travis encrypt-file command.

At this point, it would also be a good idea to run travis lint to check that the resulting .travis.yml is correct.