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.

Basics

• 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: https://git.example.com/project or git://git.example.com/project

  • Subversion: http://svn.example.com/project/trunk

    • 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: http://hg.example.com/project

  • Perforce: perforce.example.com:1111

• 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).

    Note: If your existing Maven settings might differ from the default, make sure to specify them in this field, otherwise when running Upsource under a different user (as a service, for instance) these settings might not be recognised.

• 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 upsource.user.properties
  2. Add the following line to that file: gradle.home.directory=<gradle_home>. Use double backslashes in the specified path (e.g. C:\\Users\\Jet\\Gradle)
  3. Restart Upsource

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.

Note: If you use YouTrack and specified it in the Tracker type field below, you don’t have to add link for it - its issue ID’s will be recognised and turned into links automatically.

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.

Finish

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.