Skip to content
Branch: master
Find file Copy path
Find file Copy path
4 contributors

Users who have contributed to this file

@byroot @airhorns @michelboaventura @noqcks
161 lines (122 sloc) 7.74 KB

Shipit setup guide


At this point Shipit is mostly a Rails engine, so setting it up in production requires some Rails development knowledge.

Deploying and hosting a Rails application is not trivial, and this document assumes you know how to do it.

In the future we'd like to provide it fully packaged inside a Docker container, but it hasn't been done yet.

Creating the Rails app

Shipit requires a database (MySQL, PostgreSQL or SQLite3), Redis, and Ruby 2.3 or superior.

Shipit provides you with a Rails template. To bootstrap your Shipit installation:

  1. If you don't have Rails installed, run this command: gem install rails -v 5.2
  2. Run this command: rails _5.2_ new shipit --skip-action-cable --skip-turbolinks --skip-action-mailer --skip-active-storage -m

Creating the GitHub App

Shipit needs a GitHub App to authenticate users, receive Webhooks and access the API.

You can create a new one for your organization at<your-org>/settings/apps/new, or for a regular user.

  • Homepage URL: The URL where Shipit will be deployed, e.g.
  • User authorization callback URL: It must be set to <homepage>/github/auth/github/callback, e.g.
  • Setup URL: Leave it empty.
  • Webhook URL: It must be set to <homepage>/webhooks, e.g.
  • Webhook secret (optional): Fill it with some randomly generated string, and keep it in clear on the side, you'll need it later.
  • Permissions:
    • Repository metadata: Read-only
    • Commit statuses: Read-only
    • Checks: Read & write
    • Deployments: Read & write
    • Pull requests: Read & write
    • Organization members: Read-only
    • Repository contents: Read & write (to allow merging)
    • Issues: Read & write (to allow closing related issues on merge)
  • Events:
    • Status
    • Pull request
    • Push
    • Membership
    • Check suite
    • Check run

Installing the GitHub App on your organization

Once it's created, make sure it's installed on your organization via the Install App menu on the side.

Updating the config/secrets.yml

The config/secrets.yml file will hold your secrets, by default it is ignored by git, so it's up to you to decide how secrets are deployed in production, as Rails doesn't enforce any method.

It should look like this:

  secret_key_base: some-long-string
  redis_url: "redis://redis-host"
    app_id: 42
    installation_id: 43
    bot_login: "my-app[bot]"
    webhook_secret: some-secret-value
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      -----END RSA PRIVATE KEY-----
      id: Iv1.bf2c2c45b449bfd9
      secret: ef694cd6e45223075d78d138ef014049052665f1
    domain: # The domain name of your GitHub Enterprise instance, leave it empty if you use

secret_key_base Should be generated automatically by Rails. It is used for signing session cookies etc.

host Should specify the domain of your shipit instance, e.g.

redis_url Should point to a working Redis database.

github.app_id The GitHub App ID, it can be found under General > About

github.installation_id The ID of your GitHub App installation, it can be found under Organization Settings > Installed GitHub Apps > Configure. Then look at the URL it should follow this pattern:<you-org>/settings/installations/<app-id>.

github.bot_login The login of the App [bot] user. Every GitHub App have an associated [bot] user which acts as the author of the App actions through the API, for example when an App merges a Pull Request. It should be the App "slug" with the suffix [bot]. For example if your app settings URL is, the bot user should be acme-shipit[bot]. If you are unsure, you can leave it empty.

github.webhook_secret If you've set a webhook secret during the App creating, you should copy it here.

github.private_key In your GitHub App settings, on the General section, you can generate and download a private key. You will end up with a .pem file and you need to copy it's content here. and github.oauth.secret In your GitHub App settings, on the General section, you can find these two at the bottom of the page.

github.oauth.teams optional, required only if you want to restrict access to a set of GitHub teams.

If it's missing, the Shipit installation will be public unless you setup another authentication method.

After you change the list of teams, you have to invoke bin/rake teams:fetch to prefetch the team members.

For example:

      id: (your application's Client ID)
      secret: (your application's Client Secret)
        - Shipit/team
        - Shipit/another_team

commands_inactivity_timeout is the duration after which Shipit will terminate a command if no ouput was received. Default is 300 (5 minutes).

For example:

  commands_inactivity_timeout: 900 # 15 minutes

default_merge_method is the merge method used by the merge queue unless specified otherwise in the stack's shipit.yml. Can be either merge, rebase, or squash. If not set it will default to merge.

For example:

  default_merge_method: squash

Running Cron

Shipit requires some periodic tasks to be executed to function properly. If you're running on Heroku, you can use the Heroku Scheduler add on to run Shipit cron jobs, though it will only run at a maximum frequency of once every 10 minutes.

  • Run bin/rake cron:minutely as close to every minute as possible
  • Run bin/rake cron:hourly as close to every hour as possible
You can’t perform that action at this time.