WARNING: This code is an early-access release; we wrote it for ourselves and it still harbors a lot of Herokuisms. You will probably have to adapt it to your needs if you want to use it.

Starboard is a tool which creates Trello boards for tracking the various tasks necessary when onboarding, offboarding, or crossboarding employees. We use Trello extensively within Heroku, and Starboard makes it easy to manage HR transitions from inside Trello.

The tasks themselves are authored as markdown files. When you run starboard, it resolves which tasks are relevant for the given employee and target team, and creates a new Trello board from the relevant markdown files.

Because the files are markdown (and stored in git), they're accessible to everyone in the company. Improvements to onboarding can come from anyone in the form of a pull request to the relevant guide.

Go to your deployed instance of Starboard, authorize with Trello, fill out the form and twiddle your thumbs while Starboard does its thing. When it finishes, you'll be redirected to your shiny new board.

Starboard depends on a specially-structured GitHub repository which contains the markdown guides. See the template repository for an example and more documentation.

First, you'll need to create a GitHub repository containing the guides themselves. More information about the format of this repository is available as part of the template repository.

Starboard limits access by means of checking that the user has access to a specific Trello organization.

Warning: users who don't have access to the Trello org cannot create boards, but can still access the starboard frontend and nothing prevents them from reverse-engineering the requests to fetch the raw markdown guides. If this is a problem for you, limit access to the webapp by other means.

You can use the old way and

• Clone the code
• Create an app
• Add a memcached add-on
• Push the code

You will also have to set a few configuration variables.

• TRELLO_ORGANIZATION The trello organisation where the boards are created.
• TRELLO_KEY The trello API key that can be found at https://trello.com/1/appKey/generate
• GITHUB_TOKEN A GitHub access token to get the guides out of your repository. You can create an OAuth app and generate a token or use a personal access token. Please check https://help.GitHub.com/articles/creating-an-access-token-for-command-line-use and use a private repo if you want to keep your content private.
• GITHUB_REPO An orgname/reponame identifier of the GitHub repository containing your guides.

In order for starboard to be aware of updates to your guides, you will need to create a webhook.

Follow the GitHub guide about webhooks creation and add a hook for https://<YOUR_HEROKU_APP>.herokuapp.com/guides?t=<YOUR_SECRET_HOOK_TOKEN>

When you first deploy the app, you'll need to bootstrap the cache. There are two ways to accomplish this:

1. Update your guides after installing the app and setting up the webhook. The update will cause Starboard to cache your guides.

2. Trigger the same mechanism, but manually: curl -X POST https://<YOUR_HEROKU_APP>.herokuapp.com/guides?t=<YOUR_SECRET_HOOK_TOKEN>

Hooray! Head over to https://<YOUR_APP>.herokuapp.com and go to town.

You can regenerate an access token via this curl command.

curl -vvv -X POST -H "Content-type: application/json" -u <USERNAME> -H "X-GitHub-OTP: <2FACODE IF YOU 2FA>" -d '{"scopes":["repo"],"note":"starboard access","client_id":"<APP_CLIENT_ID>","client_secret":"<APP_SECRET>"}' https://api.GitHub.com/authorizations