About Collab.SaM

Collab.SaM (pronounced collab dot sam) is a utility offered by the Center for Simulation and Modeling at the University of Pittsburgh. The goal of Collab.SaM is to encourage and enhance collaboration among Pitt researchers by providing a seamless and user-friendly platform for project management/software development related to simulation and modeling and high performance computing. Further, it provides an interface for users to leverage the expertise of the SaM consultants for domain specific problems.

For each project, Collab.SaM offers:

Additionally, each project features fine-grained user permissions: Project administrators can control read/write access to every aspect of the web interface, and more importantly to code repositories.

Getting Started

To get started please log in and create a new ticket over at Core.SaM. Please include the following information:

Don't have an account on Core.SaM? Then request one here.


Here are some screenshots of the features discussed above (click for high-resolution):


Ticketing System

Version Control

Source Code Browser




User Permissions


User Documentation

Sign up for developer notifications:

Stay active in project development by getting email notifications when new tickets are created or when existing tickets are modified.

Make sure you are logged in, then select Preferences and then the Announcements tab:

  1. To opt-in select the @developers checkbox.
  2. If you would like notification emails to go to a different address enter it into the box.
  3. Click the Save changes button to save your changes.

Now you should receive email notifications for all changes to tickets that feature @developers in the cc field. @developers is included in the cc field by default.

Checking out a subversion repository:

  • Access to all project repositories is restricted by default.
  • The project-admin for a specific project can grant a user read/write access to the repository.
  • To check out the trunk of a subversion repository:
    svn co https://collab.sam.pitt.edu/svn/projectname/trunk projectname
  • You will be prompted for your Pitt password. IMPORTANT NOTE: If you are using a terminal in which your shell username is NOT the same as your Pitt username please pass the username option to co:
    svn co --username pittID https://collab.sam.pitt.edu/svn/projectname/trunk projectname
  • To check out a branch of a subversion repository:
    svn co https://collab.sam.pitt.edu/svn/projectname/branches/branchname branchname

Cloning a git repository:

  • The project-admin for a specific project must grant a user read/write access to the repository.
  • IMPORTANT NOTE: Access to git repositories is controlled via public keys. You must have your project-admin upload your public key and provide appropriate permissions before you are able to clone, push or pull into a git repository. Project-admins: see the 'uploading public keys for git' section below.
  • To clone a git repository:
    git clone git@collab.sam.pitt.edu:projectname

Creating new tickets

To create a new ticket, click on the New Ticket tab. This option is only available to project-admins and users who are developers.

  • Enter a title for the ticket in the Summary box.
  • Describe the ticket in the description box. Many different formatting options are possible in the description. Also, almost every single aspect of your project can be referenced here with wiki formatting. See the image below for an example.
  • Any of the drop down boxes can be used to further describe the ticket. If the project-admin has defined Milestones, and this ticket represents a step towards a specific milestone then select the appropriate milestone from the list.
  • By default all developers will be notified of the new ticket, so long as they have signed up for notifications.
  • A preview of how the ticket will look is shown below. This is useful for verifying that the syntax of your markups is correct.
  • To create the ticket click on the Create ticket box. If you have any files to attach to the ticket, check the I have files to attach to this ticket box before creating the ticket. The next screen will then prompt you to upload your attachments.

Linking commit messages to the ticketing system:

This ticketing system is hooked into changeset notifications and searches commit messages for text in the form of:

command #1
command #1, #2
command #1 & #2
command #1 and #2

Instead of the short-hand syntax '#1', 'ticket:1' can be used as well, e.g.:

command ticket:#1
command ticket:#1, ticket:#2
command ticket:#1 & ticket:#2
command ticket:#1 and ticket:#2

In addition, the ':' character can be omitted and issue or bug can be used instead of ticket.

You can have more than one command in a message. The following commands are supported. There is more than one spelling for each command, to make this as user-friendly as possible.

close, closed, closes, fix, fixed, fixes

The specified tickets are closed, and the commit message is added to them as a comment.

references, refs, addresses, re, see

The specified tickets are left in their current status, and the commit message is added to them as a comment.

A fairly complicated example of what you can do is with a commit message of:

svn ci -m "Changed blah and foo to do this or that. Fixes #10 and #12, and refs #12."

with svn, or with git:

git commit -m "Changed blah and foo to do this or that. Fixes #10 and #12, and refs #12."

This will close #10 and #12, and add a note to #12.

Wiki editing:

All wiki pages use the Wiki Formatting syntax. Please see the cheat sheet for a quick overview.

In order to edit, create or add attachments to the wiki pages of a specific project, you must have developer permissions for that project. Contact the project-admin to request permissions.

  • Edit an existing wiki page: First navigate to that wiki page, then click the Edit this page button at the bottom of the page.
  • Create a new wiki page: First you must create a link to the new page from an existing page. To do this edit the existing page and add a link to the new page. Save your changes. You should see the new link you created with a question mark next to it. Click on the new link, then click on Create this page.
  • Adding an image or attachment: From an existing wiki page, click the Attach file button at the bottom of the page. Upload the file, provide a description and select Add attachment. To use the image inline in the wiki text see the Images section.

Collab.SaM is powered by Trac. For a complete reference see the Trac User Guide.

Admin Documentation

Role of project-admin:

There is only one project-admin per project. The project-admin has the following responsibilities, all of which can be managed through the Admin tab when logged in:
  • Adding collaborators (users) to the project.
  • Setting the permissions for users.
  • Controlling access to repositories.
  • Administration of milestones, ticketing and forums.

Adding users and setting permissions:

  1. To add a users click on the Permissions link along the left sidebar.
  2. Under Add Subject to Group enter the users PittID in the Subject box.
  3. In the group box enter developers.
  4. Then click add. The user should now appear in the appropriate group under the Group Membership section.
A note about permissions:
  • By default someone who visits the site and is not logged is considered in the anonymous group. As the Permissions indicate an anonymous viewer will only see the wiki pages and search.
  • An authenticated user is someone who is logged in with their PittID. An authenticated user basically has read access to a significant portion of the project. However, an authenticated user CANNOT view source code by default.
  • A developer is someone who will be collaborating on the project. A developer is able to view the source code, make tickets, comment on tickets, modify the wiki pages and view any file attachments. When adding collaborators to your project it is intended that you assign them to the developer group.

Any of these default permissions can be modified using the Grant Permission box to add a feature to a specific user or group. Permissions can be removed by checking the appropriate action for a group, or by removing a user from a group membership and then clicking the Remove selected items button.

Setting Subversion repository permissions:

By default subversion repositories are completely private. When a new project is created, the project-admin must set the initial permissions before anyone (project-admin included!) can access the repository. The Subversion Access panel provides a web UI to the familiar SVN path-based authorization protocol.

It is easiest to demonstrate how path-based authorization works with an example. Suppose we have an SVN repository named foobar and foobar has the following directory structure:

|-- branches
| |-- branch1
| `-- branch2
|-- tags
`-- trunk

Project foobar has 4 collaborators, user1, user2, user3 and user4. Each user should have read access to the entire repository. Additionally, user1 has write access to entire repository, user2 has write access to any branches, user3 only has write access to branch1, and user4 only has write access to branch2.

  • In the above example we have identified 4 paths that require specific permissions. The root of the repository (foobar:/), the branches directory (foobar:/branches), the branch1 directory (foobar:/branches/branch1), and the branch2 directory (foobar:/branches/branch2).
  • The first step is then to add these 4 paths. To do this enter the path name and press Add in the Add Path: section. The pathname should follow the syntax above, the name of the repository followed by a colon followed by some path in the repository.
  • Successfully added paths will appear under the Subversion Paths section.

Now that the paths have been added, we can specify the user permissions for each path. IMPORTANT: In order to specify repository permissions for a user, the user must already have been added to the project. See Adding users and setting permissions above.

  • To set permissions for a specific path, first click on the pathname under Subversion Paths.
  • Doing so will add a new section to the top of the page, titled Add Path Member to pathname. Select the username from the subject list. Check the appropriate permissions and click Add.
  • A successfully added user and their permissions will appear underneath the appropriate pathname in the Subversion Paths section.

To add permissions for the other directories, select another pathname from the Subversion Paths list and add the appropriate user permissions.

Uploading public keys for Git:

  1. To add a public key click on the Users link along the left sidebar.
  2. In the name field, enter the users Pitt ID.
  3. Click on Choose File to browse for the public key on your system. Any developers on the project will need to send the project-admin their public key for upload. Developers cannot add their own public keys.
  4. Click the Add button to upload the public key.

Multiple keys for the same user: A user can have multiple public keys, i.e. lets say they need access from a home laptop and a work desktop. In order to prevent overwriting an existing key the users PittID must be appended with an @tag, where tag should be descriptive. See the example in the figure.

Once a user's public key(s) have been uploaded. The git repository permissions can be set for that specific key. See the next section for instructions on how to do that.

Setting Git repository permissions:

  1. To set permissions for a git repository click on Permissions link under Version Control link along the left sidebar.
  2. Select the appropriate permissions for each user (public key). 'R' corresponds to read permissions, 'W' to write permissions and '+' allows a user to rewind. For more information see the guide on basic access control.
  3. Click the Update repository permissions button to save your changes.

Creating milestones:

  1. To create a new milestone click on the Milestones link along the left sidebar under Ticket System.
  2. In the Name box enter a name for the milestone.
  3. In the Due box enter a due date for the milestone.
  4. Then click add. The new milestone should now be listed.

Existing milestones can be editted from the same menu.

  • Click on an existing milestone from the list.
  • In the new screen the name of the milestone and due date can be adjusted.
  • Further a description for the milestone can be added.

The Roadmap tab displays the project's milestones with descriptions. Also, when tickets are created for a given milestone, the Roadmap will represent the progress towards reaching the milestone.

Collab.SaM is powered by Trac. For a complete reference see the Trac Administrator Guide.


Coming soon.
collab.SaM | www.SaM | core.SaM | pitt.edu | find.pitt