docs/adding_a_project.md
<!---
Do not edit the adding_a_project.md file, as it is generated by the assemble_docs rake task
If you wish to make a change in that file, edit the files in the docs/adding_a_project directory and run the rake task
-->
# Adding a project
After logging in, click the "New Project" button and enter
the details for a build you want to display on ProjectMonitor. The "Name" and
"Project Type" are required. You will need to either connect your service via
Webhooks or polling.
To connect via Webhooks, the project settings page will display the Webhook URL
you'll need to enter in your CI instance's settings. The Webhook URL isn't generated
until after a project is created, so you'll need to select the 'Webhooks' radio button,
click 'Create', and then click the 'Edit' button for the newly-created project
to get the Webhook URL.
In order for Webhooks to work, you'll also need to make sure that the machine hosting
ProjectMonitor is accessible by the machine hosting your CI instance.
If you want to set up a project to connect via polling instead, you'll typically need
to enter the base URL, build name or ID, and your login credentials with the CI service.
## CircleCI
__Webhooks__
1. Configure webhooks by creating a `circle.yml` file in your repository. This has the ability to configure your webhooks.
2. copy the following into your `circle.yml` replacing the url with the url you get from clicking the webhooks button below
~~~
notify:
webhooks:
- url: https://site.com/path/to/your/webhooks/url
~~~
__Polling__
1. Add your CircleCI username to the form below
2. Add your repo name to the field Build Name in the form below
2. Add an API token from your [account dashboard](https://circleci.com/account/api).
To test it, view it in your browser or call the API using curl:
~~~
$ curl https://circleci.com/api/v1/me?circle-token=:token
~~~
You should see a response like the following:
~~~
{
"user_key_fingerprint" : null,
"days_left_in_trial" : -238,
"plan" : "p16",
"trial_end" : "2011-12-28T22:02:15Z",
"basic_email_prefs" : "smart",
"admin" : true,
"login" : "pbiggar"
}
~~~
Finally, add the API token to the "Auth Token" field in the form below.
## CodeShip
CodeShip only supports webhooks
1. Go to your codeship account
2. Select your project that you want to have on ProjectMonitor
3. Click __Project Settings > Notifications__
4. In the Webhook section, check "enabled" and enter the url found on this page after you click the "webhooks" button
## Concourse
__Polling__
If you want to connect to Concourse via polling, you'll need to ensure that your Concourse instance is accessible by the machine running ProjectMonitor.
1. Enter the URL for the Concourse server into the Base URL field in the form below
2. Enter the job name into the form below
## CruiseControl.NET
_note: this is not the cruisecontrol.rb found on sourceforge- rather it is CruiseControl.NET found at http://cruisecontrolnet.org/_
__Polling__
1. Click the RSS Feed on your project page
2. Copy-paste the link that you visit into the form under RSS Feed URL
## Jenkins
__Polling__
If you want to connect to Jenkins via polling, you'll need to ensure that your Jenkins instance is accessible by the machine running ProjectMonitor.
1. Enter the URL for the Jenkins server into the Base URL field in the form below
2. Enter the project name into the Build Name field in the form below
__Webhooks__
If you want Jenkins to connect via Webhooks, you will need the
[Jenkins notification plugin](https://wiki.jenkins-ci.org/display/JENKINS/Notification+Plugin).
## Semaphore
To configure Semaphore, you must create the Semaphore API URL.
The format of this URL is
~~~
semaphoreci.com/api/v1/projects/<Project hash_id>/<branch id>?auth_token=<auth_token>
~~~
You can get the Project hash_id from your project's settings api page. From the Semaphore main page,
1. Clicking the setting button for your project
2. Clicking 'Admin' on the left menu
You can get the auth token from your account page. Get there by
1. Clicking your username in the upper-right corner
2. Clicking 'Settings'
In order to get your branch id, you have two options.
One way to do it is to just use the name of the branch
* If a branch is called "master", then you can use "master".
* If it has non-alphabetic characters, they get replaced - for example a branch called "ns/rails-assets" would be "ns-rails-assets".
* The ID formatted in this way is visible on the URL of the branch page.
An alternate way is to retrieve the numeric id from Semaphore using their API.
Enter the following url into your browser window
~~~
semaphoreci.com/api/v1/projects/<Project hash_id>/branches
~~~
where the project hash_id is the same as the one from your API page. Get the ID from the returned json file for the branch you are interested in tracking and insert it in the original URL from the top of these instructions.
Example result
~~~
[{"id":383597,"name":"master","branch_url":"path/to/project/branch"}]
~~~
Finally, enter the finished API URL in the form below## TDDium / Solano CI
TDDium / Solano only supports connecting via polling, not Webhooks.
In order to get polling configured, you will need to:
1. Log in to your Solano dashboard, go to Organizations using the drop down in the top right corner.
2. Click on organization settings for the appropriate organization.
3. In the left-hand nav, click "CC Menu (XML Status)"
That should take you to a URL that looks like:
https://ci.solanolabs.com/cc/SOME-TOKEN-HERE/cctray.xml
The value for "SOME-TOKEN-HERE" is the TDDium authentication token you'll need to paste into the ProjectMonitor settings.
If you access that link, the XML returned will look something like:
~~~
<Projects>
<Project name="FooBar (master)" webUrl="https://ci.solanolabs.com:443/reports/1359512" lastBuildLabel="1359512" lastBuildTime="2015-03-24 17:19:48" lastBuildStatus="Unknown" activity="Sleeping"/>
</Projects>
~~~
The "TDDium Project Name" field in the ProjectManager settings will need to be set to the full value of the Project
name attribute, complete with the branch name in parentheses (in this case, "FooBar (master)").
The Base URL is the host name of the CI server. If you are using the Solano Labs server, the base URL is found is in the XML return. In this case it is https://ci.solanolabs.com:443
## TeamCity
For TeamCity projects, find the buildTypeId (usually something like 'bt2') from the URL, which should look like one of the following:
http://teamcity:8111/app/rest/builds?locator=running:all,buildType:
http://teamcity:8111/viewType.html?buildTypeId=
http://teamcity:8111/viewLog.html?buildId=1&tab=buildResultsDiv&buildTypeId=
You will also need a valid user account and password.
If you want TeamCity to connect via Webhooks, you'll need to install the
[TcWebHooks plugin](http://sourceforge.net/apps/trac/tcplugins/wiki/TcWebHooks) on
your TeamCity instance. When setting up the webhook in TeamCity, make sure the payload
format is set to "JSON" (it might show up as "JSON (beta)").
If you want to connect to TeamCity via polling, you will need to ensure that your TeamCity instance
is accessible by the machine running ProjectMonitor.
## TeamCity Rest
For TeamCity REST projects, find the buildTypeId. You can find this by
1. Selecting the Project from TeamCity
2. Selecting the build associated with that project
3. Looking at the URL for that build. ```www.domain.com/viewType.html?buildTypeId=YourProject_BuildTypeId```
In the example above, the build type id is the last argument in the URL
You will also need a valid user account and password.
If you want TeamCity to connect via Webhooks, you'll need to install the
[TcWebHooks plugin](http://sourceforge.net/apps/trac/tcplugins/wiki/TcWebHooks) on
your TeamCity instance. When setting up the webhook in TeamCity, make sure the payload
format is set to "JSON" (it might show up as "JSON (beta)").
If you want to connect to TeamCity via polling, you will need to ensure that your TeamCity instance
is accessible by the machine running ProjectMonitor.
## Travis Pro
If you want Travis Pro to connect via polling, you will need your Travis CI token.
You can find this by logging into [Travis CI Pro](https://magnum.travis-ci.com),
clicking your name in the top-right corner, choosing *Accounts*,
then choosing the *Profile* tab. Copy the value listed as your *Token*
into the Project Monitor *New Project* page as your **Travis Pro Token**.
## Travis
__Polling__
Enter the GitHub account, repository, and branch name (if it isn't master) for the git repository being built by Travis CI
__Webhooks__
If you want Travis to connect via Webhooks, you will need to enter the same information required by polling (e.g.
GitHub account, repository, and optionally branch name) as well as following Travis CI's instructions for setting up webhooks