Use of this software is subject to important terms and conditions as set forth in the License file
A web interface for deployments.
View the current status of all your projects:
Allow anyone to watch deploys as they happen:
View all recent deploys across all projects:
Samson works by ensuring a git repository for a project is up-to-date, and then executes the commands associated with a stage. If you want to find out exactly what's going on, have a read through JobExecution.
Streaming is done through a controller that uses server-sent events to display to the client.
- MySQL, Postgresql, or SQLite
- Memcache
- Ruby (currently 2.1.1)
Run the bootstrap script to use the test credentials.
script/bootstrap
rails s
open http://localhost:3000- Add a new project http://localhost:3000/projects/new
- name: example-project url: git@github.com:samson-test-org/example-project.git
- Create a Stage
- Deploy!
For a real setup:
Set up a production block in database.yml with the settings to connect to your DB then run RAILS_ENV=production bundle exec rake db:setup
Configure config/puma.rb as you need. See puma's documentation for details. You can start the server using this file by doing puma -C config/puma.rb.
Set the following config in your .env file:
SECRET_TOKEN for Rails, generated during script/bootstrap.
GITHUB_TOKEN
This is a personal access token that Samson uses to access project repositories, commits, files and pull requests.
- Navigate to https://github.com/settings/tokens/new to generate a new personal access token
- Choose scope including repo, read:org, user and then generate the token
- You should now have a personal access token to populate the .env file with
GITHUB_CLIENT_ID and GITHUB_SECRET
- Navigate to https://github.com/settings/applications/new and register a new OAuth application
- Set the Homepage URL to http://localhost:3000
- Set the Authorization callback URL to http://localhost:3000/auth/github/callback
- You should now have Client ID and Client Secret values to populate the .env file with
DEFAULT_URL absolute url to samson (used by the mailer), e.g. http://localhost:3000
Samson can use an organisation's teams to provide default roles to users authenticating with GitHub.
GITHUB_ORGANIZATION name of the organisation to read teams from, e.g. zendesk
GITHUB_ADMIN_TEAM members of this team automatically become Samson admins, e.g. owners
GITHUB_DEPLOY_TEAM members of this team automatically become Samson deployers, e.g. deployers
Samson can use custom GitHub endpoints if, for example, you are using GitHub enterprise.
GITHUB_WEB_URL used for GitHub interface links, e.g. compare screens, OAuth authorization
GITHUB_API_URL used for GitHub API access
GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
- Navigate to https://console.developers.google.com/project and create a new project
- Enter a name and a unique project id
- Once the project is provisioned, click APIs & auth
- Turn on Contacts API and Google+ API (they are needed by Samson to get email and avatar)
- Click the Credentials link and then create a new Client ID
- Set the Authorized JavaScript Origins to http://localhost:3000
- Set the Authorized Redirect URI to http://localhost:3000/auth/google/callback
- Create the Client ID
- You should now have Client ID and Client secret values to populate the .env file with
NEWRELIC_API_KEY
You may fill in using the instructions below if you would like a dynamic chart of response time and throughput during deploys. https://docs.newrelic.com/docs/features/getting-started-with-the-new-relic-rest-api#setup
| Role | Description |
|---|---|
| Viewer | Can view all deploys. |
| Deployer | Viewer + ability to deploy projects. |
| Admin | Deployer + can setup and configure projects. |
| Super Admin | Admin + management of user roles. |
The first user that logs into Samson will automatically become a super admin.
Samson can be integrated with CI services through webhooks. You can find a link to webhook on every project page. There are links on webhook pages that you will want to add to your project settings on your CI service. Set up your webhooks and the deployment process can be automated.
-> Push to branch(e.g. master) -> CI validation -> CI makes webhook call -> Samson receives webhook call -> Samson checks if validation is passed -> Deploy if passed / do nothing if failed
- Travis
- You can add a webhook notification to the .travis.yml file per project
- Semaphore
- Semaphore has webhook per project settings
- Add webhook link to your semaphore project
- Tddium
- Tddium only has webhook per organisation setting
- However you can have multiple webhooks per organisation
- Add all webhooks to your organisation
- Samson will match url to see if the webhook call is for the correct project
- Jenkins
- Setup using the Notification Plugin
- Buildkite
- You can add a webhook per project under settings/notifications
- You can add any value to the 'Token' field, as it is not used
- Github
- You may add a webhook for push events
Skip a deploy:
Add "[deploy skip]" to your commit message, and Samson will ignore the webhook from CI.
- JIRA
- Datadog
- New Relic
- Flowdock
- Slack
- Github
- Hipchat: Clone of Slack plugin
In addition to automatically deploying passing commits to various stages, you
can also create an automated continuous delivery pipeline. By setting a release
branch, each new passing commit on that branch will cause a new release, with a
automatically incrementing version number. The commit will be tagged with the
version number, e.g. v42, and the release will appear in Samson.
Any stage can be configured to automatically deploy new releases. For instance, you might want each new release to be deployed to your staging environment automatically.
Samson sends StatsD basic web request metrics and metrics about deploys and threads in use. Statsd silently disables itself if no agent is running on the host. All metrics collected are prepending with 'samson.app'.
Samson now supports writing plugins to add functionality to the core app keeping the core isolated and simpler. You can thus add UI elements to pages that support it, and hook into events such as before and after deploys.
To get started execute the following and follow the on-screen instructions:
rails generate plugin MyCoolNewPlugin
Also feel free to browse the existing plugins in the 'plugins' directory to get a feel. They follow the structure of a Rails Engine.
Improvements are always welcome. Please follow these steps to contribute
- Submit a Pull Request with a detailed explaination of changes and screenshots (if UI is changing)
- Receive a 👍 from a core team member
- Core team will merge your changes
Core team is @steved, @dasch, @jwswj, @halcyonCorsair, @princemaple, @bolddane, @pswadi-zendesk.