Instructions for integrating publishing Scaladoc to CI/CD

docs_init.sh

#!/bin/bash

# This script is used for initializing the gh-pages branch

ORG_NAME=snowplow
PROJECT_NAME=snowplow-scala-analytics-sdk

PROJECT_REPO=git@github.com:$ORG_NAME/$PROJECT_NAME.git

# Using a fresh, temporary clone is safest for this procedure
pushd /tmp
git clone $PROJECT_REPO
cd $PROJECT_NAME

# Create branch with no history or content
git checkout --orphan gh-pages
git rm -rf .

# Establish the branch existence
git commit --allow-empty -m "Initialize gh-pages branch"
git push origin gh-pages

# Return to original working copy clone, we're finished with the /tmp one
popd
rm -rf /tmp/$PROJECT_NAME

Instructions_Scaladoc.md

Instructions for integrating publishing Scaladoc to CI/CD

This document is explaining what should be done in order to publish updated Scaladoc with every new version of library.

Before starting to follow these instructions, some changes need to be done in project. You can find necessary changes in this Analytics SDK commit.

Instructions:

• Initialize gh-pages branch with docs_init.sh script. You need to change PROJECT_NAME and ORG_NAME variables according to your project.
• 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.
• Finally, change ENCRYPTION_LABEL in .travis.yml to label which you get in the end travis encrypt-file command. For example, if you get the following in the output:

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

in that case ENCRYPTION_LABEL is 3afbfedfa397.

• Add changes to git and commit

Hey @aldemirenes, looks great! Couple of questions:

1. Can we re-use $PROJECT_NAME in PROJECT_REPO? That way we would have to change only one variable.
2. Am I right that our key pair can be re-used for all projects? In that case we should ask Tech Ops to generate key for us, store in our secret storage and ask them to share with engineers.