Setting up continuous integration for a project hosted on GitHub or Bitbucket and running your first build on Semaphore is easy and takes only a few clicks.
If you don't already have a Semaphore account, sign up and confirm your email address. The free account gives you unlimited CI service for open-source projects and up to 100 private builds per month.
After you have signed in on Semaphore for the first time, a welcome screen will prompt you to add your first project. Click on the "Start a Project" button to get started. If you have already added some projects on Semaphore, use the "Create new" link at the top of your screen.
The next step is to connect your Semaphore account with your GitHub and/or Bitbucket account. This will allow Semaphore to do things like present you a list of projects to select from, fetch the chosen Git repositories, and update pull request status. Select your preferred Git host.
From the next screen, select whether you would like to give Semaphore access to your public (open-source) or private projects. Access to private projects also includes access to public projects.
We will now presume that you selected Private & Public. At this point, Semaphore will redirect you to GitHub, where you will be presented a screen to authorize Semaphore to access your account via OAuth. Click "Authorize application" to continue.
Once you have confirmed permission access, Semaphore will list all your repositories. If the list is very long, you can use the search box located at the top to narrow it down. If you selected 'Private & Public' option, you will see both private and open source projects in the list.
Note: In case this is your first private project on Semaphore, this will also start a 30-day free trial of Semaphore. After the trial expires, you can continue using Semaphore for free for up to 100 private jobs, or upgrade to one of the paid plans.
In the upper-right corner of the homepage is a button “Add new project”. Once you click on it, you will get the option to choose one of the repositories (Step 1/3). If the repository is marked with an exclamation mark, this means that you don't have the permission level needed for adding a project to Semaphore.
You have to have either Admin or Owner level of permissions on GH in order to add a project to Semaphore if it’s not already added. If you are just a member of a GH organization, you will have to request approval from organization member of the Owners team. In order to do that, you have to go to this link.
Once you have requested access for the needed organization, Owner of that organization will get an email with your request and grant it. (In this case, Owner also has the option to deny the access).
After you've selected the repository, you will be asked to select a branch that you want the first build to run from (Step 2/3). Semaphore will automatically test every new branch you create, and remove the ones you delete in origin. Additional preexisting branches can be easily added from your project page later on.
In the next step (Step 3/3), enter a name for your organization on Semaphore — a space for projects that you can share with others. Organizations let you to grant different permissions to team members and delegate project management under a single account.
Note: In case you're adding an open source project, you won't see this step, although you can create an organization account for open source separately too.
If you choose to connect your Bitbucket account with your Semaphore account, the process is almost the same as adding a GitHub account, except you don't have the option to choose if you want to give Semaphore access to your public (open-source) or private projects. Bitbucket only supports giving access to both private and public repositories.
Note: If you want to add a project from Bitbucket, you have to either be its creator or belong to a Bitbucket group that has Admin rights to it.
Next, Semaphore will perform a quick analysis of the source code and generate a set of working build commands depending on your project's programming language.
In this case, we have a Ruby on Rails application for which we would like to run unit and integration tests. We'll go ahead and rename the first job.
After that we'll add a new parallel job for integration tests. You can add a parallel job by clicking "Parallel job". You can add as many jobs as you want.
We will enter a command bundle exec rspec --integration in our command editor.
Now our build settings look much better. We have 2 parallel jobs, one for unit test, second for integration test.
If your project needs to run commands that are different from what Semaphore has suggested, just use the commands editor to customize them to your needs.
At this point, you'll be ready to launch your first build. Click on "Build With These Settings" to do so. If all goes well, you should see your first successful build on Semaphore.
For more build customization options, please refer to our "Customizing your build" documentation section. Happy building!
Semaphore Docs are open source — Edit on GitHub