Upsource 2.5 Help

Creating your first project

To add your first project in Upsource:

  1. Make sure you're logged into Upsource using the administrator account. Non-admin user accounts are not eligible to create new projects.
  2. Go to http://your-host-name:port_for_upsource (or click the link for Upsource Frontend from the welcome page)
  3. Click Create a project.
  4. In the Create Project form, specify settings for your project.


  • Name: Give your project a name and type it in.
  • ID: Project ID is created automatically based on the specified project name.

Version Control

  • Project is hosted in multiple repositories: Select this option if your project is divided into a few separate repositories but building this project requires fetching all the repositories into specific locations under the root directory. Mapping multiple repositories allows you to watch and review changes in all of them from a single Upsource project.
  • Click Add repository and specify the following settings for each repository:
    • Mount path: Specify a directory inside your project where this VCS root will reside.
    • Mapping ID: A unique ID of the VCS repository. It's generated automatically, but you can specify your own.
  • Repository URL: The following formats are expected in the _Repository URL (Server name)_ field for different version control systems:
    • Git: or git://
    • Subversion:>
  • Enable branches support - You can define one or more SVN paths where Upsource should be looking for SVN branches. Use rules like +: or -: to include or exclude branches. Branch paths are relative to the repository URL specified above. Pattern may contain one * to match any number of characters in directory name.
    • Example for a standard SVN layout:
      +:trunk +:branches/*
    • Mercurial:
    • Perforce

    Important:In order for Upsource to recognise a Perforce repository, you need to:

    1. Download and install _P4:COMMAND LINE_ on the machine with your Upsource installation.
    2. For Mac OS and Linux, specify PATH to _P4:COMMAND LINE_ in your system environment variables (see P4 instructions).
    3. Restart Upsource
  • Workspace mapping

    To include the entire project, specify: //<depot>/<project>/...

    To include only selected directories of the project, list these directories followed by corresponding directories in Upsource (divided by a space). Example:

    //depot/project1/directory1/... //upsource/depot/project1/directory1/... //depot/project1/directory2/... //upsource/depot/project1/directory2/...
  • Login, Password: Specify credentials to connect to your VCS.
  • Check interval: Reflects how often Upsource checks for new revisions in the repository (every 300 seconds by default.)

If commits to your repository aren't usually made this frequently, consider setting _Check interval_ to a larger value.

See also: What is supported for each VCS

Upsource Properties

  • Build system defines whether Upsource is able to execute static code analysis in your repository and provide related features including displaying code issues, "Find usages", "Go to Declaration" etc.
  • This setting should only be considered if you are working on a Java project. If you are working on a project that doesn't use Java, you're safe to set Build system to None as code analysis for non-Java projects is not supported at this point.
  • For Java, there's a separate option for projects that use Maven irrelevant of which IDE is used to maintain code, and also an option that enables code analysis when IntelliJ IDEA is used in the project irrelevant of build system (for example, if your project is built with Ant but you're using IntelliJ IDEA, then IntelliJ IDEA_would be your choice of build system.)
  • If Maven is selected as build system:
    • Path to project model should contain the path to the parent _pom.xml_ file (relative to project root). If your project modules are hosted in multiple repositories (e.g. each module in their own repository), you can configure them all in one Upsource project, and keep the parent pom.xml in the first repo.
    • Maven settings - if your project requires non-standard Maven settings, paste the content of your maven-settings.xml here (up to 20KB).
  • If IntelliJ IDEA is selected as build system, Path to project model should contain the path to the .idea directory (relative to project root).
  • If your team developers configure their IDE so each has different .idea folder, it's still recommended to store most of the .idea folder contents in version control, only omitting the user-specific settings, such as .idea/workspace.xml and .idea/shelf. Otherwise Upsource will not be able to provide Java code insight for your project.

    If Gradle is selected as build system, Path to project model should contain the path to the build.gradle file (relative to project root). Please note: Android Studio projects are not currently supported.

    If you're planning to work on Gradle projects without a wrapper:

    1. In the <upsource_home>/conf directory, create a file
    2. Add the following line to that file:<gradle_home>. Use double backslashes in the specified path (e.g. C:\\Users\\Jet\\Gradle)
    3. Restart Upsource
  • Default branch - optionally specify the branch which you want to set as default. Setting the default branch will improve displaying the commits graph, rendering README files, comparing branches, etc.

External links

Upsource can detect references and turn them into hyperlinks. For example, issue references mentioned in commit messages or discussion comments (such as Fix PRJ-123) can be recognized by Upsource and linked to the corresponding issues in your tracker.

Click Add link and specify your tracker's URL and an issue ID pattern.

Issue Tracker Integration

Integration with known issue tracker enables additional features such as creating issues from code reviews and discussions.

Currently Upsource can integrate with YouTrack and Jira.

Please refer to Issue tracker integration for detailed instructions.


When you are done filling in the form, click Create Project (or Save changes if you're editing)

You'll be redirected to the Administration view (http://your-host-name:port_for_upsource/administration) that shows status summary for the project.

Meanwhile Upsource will start loading commit information from the repository, then fetching and indexing repository content.

All this could take a while for larger projects (up to several hours.) To track indexing progress, hover over the project name. You will most probably not be able to work with the project before these steps complete.

Upon completing them, Upsource will allow browsing code in revisions, displaying diffs in revisions, create and process code reviews etc.

Last modified: 14 September 2016