Thanks for taking the time to try Crucible. To help you make the most of your time, try these easy instructions for configuring and using Crucible.
Software developers are the intended audience for this document.
Getting Crucible up and running
Carry out these steps to setup Crucible and you will be ready for your first code review in no time. Setting up Crucible takes less than half an hour.
Basic installation is a breeze. (click to expand)
First things first, if you haven't already got Crucible up and running carry out the following steps:
- Download Crucible from the Atlassian Download Center
- Unzip the downloaded package to the desired installation directory.
- Launch Crucible from the command line, typing
run.bat (under Windows) or
./run.sh (under Linux). A Crucible console window will appear, listing the startup progress. Give it a few minutes to complete its process.
- On the same machine go to
http://localhost:8060/ (or use the hostname or IP address in place of localhost from another machine). You will be prompted to enter a license key and set the admin password.
There are a lot of installation options. To learn more, see the complete documentation.
It should only take you a few minutes to have a running instance of Crucible. If you are still struggling after twenty minutes please contact our support team for assistance. They're ready to help at any time.
Connect to Your Repository
Crucible standalone supports SCM repository systems. (click to expand)
Once installed, you need to connect Crucible to a Source Code Management (SCM) repository, so that you can get reviewing right away. You can instantly connect to the following SCMs:
Using standalone Crucible, your repositories will be accessed only on-demand. However if using Crucible with FishEye you get much deeper SCM integration for Subversion , Git, Perforce IBM ClearCase and CVS. FishEye allows advanced searching and rapid access to repository contents (it also requires pre-scanning your repositories). Note that your Crucible evaluation license enables FishEye.
See the configuration documentation for more.
Set Up Your Crucible Project(s)
Work streams in Crucible are organised into projects. (click to expand)
Your Crucible instance must have at least one project, in a fresh install this is imaginatively named "Default Project". It is a good idea to rename this to something more personal. If you plan on having multiple projects, you might also want to change the review key when renaming the Default Project (it defaults to CR), this should not be the same as any other keys (e.g. JIRA project, Bamboo plan) that you use. At Atlassian we prefix our JIRA project keys with CR-, e.g. the FishEye project's key is CR-FE, but you can use whatever you like.
Obviously Crucible projects let you organise your reviews into logical groups, but they serve several other purposes.
- Access control - is set at the project level
- Permission schemes - which roles can do what
- Default participants - e.g. auto add the team lead to every review
- Default length - set the number of week days to set the due date for a new review
You can also associate JIRA issue tracker(s) with your project, by configuring JIRA Integration in Crucible.
Configure Mail (optional)
Email notifications are a great way to keep up with Crucible activity. (click to expand)
Crucible can deliver email feeds based on user configured parameters. For example, you can watch the contributions of a specific colleague or changes to a branch of code you're working on. To take advantage of this feature, you will need to tell Crucible about your SMTP server.
You can also configure custom templates for notification email messages and fine-tune the frequency of email delivery, for example, choosing a daily digest.
Move onto the next step to learn about Crucible's integration with JIRA, Atlassian's award-winning issue tracker.
Configure JIRA (optional)
Crucible integrates with JIRA, Atlassian's enterprise issue tracker. (click to expand)
- If you already have a JIRA server set up, you can go ahead and set up integration between the two. Once established, activity on relevant JIRA issues will appear in the Crucible activity stream. JIRA issue keys will also be hyperlinked, also a small information window will load when you mouse-over JIRA issue keys.
- Visit the Crucible documentation for instructions on how to set up JIRA integration in Crucible.
Your Crucible instance is now established. (click to expand)
Congratulations! Our support records indicate that over 80% of support calls happen during this installation phase. Once you have made it this far, the rest of the evaluation ought to flow smoothly.
There are heaps of tweaks and configuration options that you can experiment with. Check out the Crucible Administrator's Guide for more information.
Otherwise, move on to the next step and launch right into lightweight code reviews.
Learning the Basics
Now that you've got Crucible set up, you can start using Crucible's code review features in earnest. Creating reviews, pre-commit and post-commit reviews, notifications, and much more.
Reviewing Quick Start
Jump into code reviews instantly with Crucible. (click to expand)
Using Crucible is easy and lightweight, facilitating rapid and effective reviews. Jump right in and create your first review now .
There are many carry out reviews with Crucible. In some form or another you need to go through the following steps. Each step is linked to documentation, but you probably won't need it.
- Create the review - Select "Create Review" from the "Tools" menu in the top right of any page.
- Add content to the review - Choose some stuff to review, either from a repository you have configured or by uploading something.
- Choose reviewers - if you haven't added users or [configured ldap] you won't be able to do this, you'll get a warning when you try to start the review, but you can ignore that
- Start the review - click the start button in the create dialog or in the top right hand corner of the review page
- Add some comments - use one of the many "add a comment" links or simply click on the lines of source your want to comment on
- Summarise and close the review - when you are finished with a review, it needs to be closed. Summarise is the state between "under review" and "closed", most of the time you will summarise and close at the same time. Alternatively you can abandon a review, which effectively moves it to the trash.
Now that you've got a feeling for the basic review concepts, its worthwhile taking a moment to customise your instance.
Pre and Post Commit Reviews
Create reviews before or after you check-in. (Click to expand)
Crucible allows you to review a change before it has been committed. To do this, you upload a patch file to the 'Patch' tab (or paste it in as text) when creating a review. You must first generate this patch file from your repository, using either commands built into your IDE, or via the repository command-line tools.
- Create a new review. From the 'Tools' menu in Crucible, select 'Create Review'.
- Click 'Pre-Commit - Upload a patch file to be reviewed'. The 'patch upload' dialog appears. Click 'Browse', locate your file, then click 'Upload'. Crucible will now search for matches in the files in its database. Crucible will analyse all the paths in the patch, find the branches containing all those paths, then anchor the patch to the trunk or the branch with the most recent commit activity.
Learn more about pre-commit (patch) reviews here.
- Create a new review. From the 'Tools' menu in Crucible, select 'Create Review'.
- To add files to a review, click the 'Files' option on the left navigation bar of the Manage Files dialog. The Files view opens.
Learn more about post commit reviews here.
Creating Reviews Fields
Fill in the fields that are relevant for your review. (click to expand)
- When adding reviewers, Crucible will suggest reviewers who have worked on the relevant files, but also don't have a big review backlog.
- You can set a specific due date for each review as you create them, or set a default duration for each review under a project.
- You can easily link to JIRA issues in reviews and associate reviews with JIRA issues.
Working with Reviews
Identify defects in your code and tag them in Crucible. (click to expand)
A number of context windows appear when hovering your mouse over links. (click to expand)
Try hovering your mouse over the following links in Crucible to see the context windows:
Activity & People
Crucible adds a modern social web dimension to the usually impersonal data stored in your Source Code Management (SCM) repository.
You can see commits and updates from the users in Crucible rolling by. (click to expand)
This information appears as a stream on the Dashboard and oher index pages, sorted chronologically showing you the latest changes. Updates can be viewed as an inline stream or RSS feed. See the documentation for more.
In Crucible, you can view useful updates and statistics from your team. (click to expand)
On the People index page, you can see the commit history in global lines of code (LOC) that each person has contributed (expressed as a line graph) and their total number of commits. Also, the most recent piece of activity is shown as a clickable item. See the documentation for more.
Each person who makes code changes has a page. (click to expand)
You can click on a person's name to see detailed information about their code reviews, showing details of their work and summaries of their activity. Additionally, you can see their work on tracked issues and additions to the repository if using Crucible with FishEye and JIRA integration is set up. See the documentation for more.
Your Personal Dashboard
See your own work at a glance and a stream of work items that are relevant to you. (click to expand)
Click the 'Dashboard' tab to see a stream of all your own activity; your reviews; your personal code commits (if you are using FishEye); and your tracked issue updates (if you are using JIRA). See the documentation for more.
Favourites as Bookmarks
Everything in Crucible can be bookmarked. (click to expand)
In Crucible, you can add the following items as favourites:
- Review Comment Threads,
- Files or Folders,
Once items are added to your favourites, a list is created. You can then view it or see a stream of all activity relating to your favourites.
See the documentation for more.
Subscribe to Crucible Updates
Keep track of Crucible activity when your Crucible session is closed. (click to expand)
Find a specific review or all of them with easy search options. (click to expand)
Searching for Reviews:
See the documentation for more.
Searching for comments:
Crucible give you the ability to search and filter review comments. Search or filter by comment content, defect classification, specific role(s), date and much more. Learn more here.
When you type in the search box, matches are instantly shown below. (click to expand)
You can quickly find what you are looking for by typing one word or part of the name of what you are looking for. Crucible's Quick Nav feature will immediately show matches and suggestions below, before you've even pressed Enter or activated a proper search. Try typing a review's issue ID to go directly to that page.
Crucible will allow you to go beyond commenting on source code. Iterative reviews, reports and auditing, plugins, JIRA integration, IDE integration, and much more.
Files are always up to date
Crucible allows you to review iteratively, so you can keep focused on the most recent file. (click to expand)
- When files in a review become outdated, Crucible informs you with the File Outdated Menu. You can then easily update the file with one click (Iterative Review).
Review Multiple Revisions
Select the files that you want to review
Crucible is extensible, allowing you to create your own reports and sent info to other systems. (click to expand)
You can create your own report as a plugin and have it appear in the menu. For example, the 'Review Blockers' report that appears in the user interface is actually a plugin, added in to Crucible. You can use this plugin as a basis to create your own custom reports and add them in to Crucible. See the Crucible developer documentation for more.
Using the REST API
Extend Crucible. (click to expand)
With its own API (Application Programming Interface), Crucible is extensible. If you need Crucible to do more than it ships with and you've got programming chops of your own, the API allows you to build extensions to the application to suit your needs.
See the API documentation for more.
Integrate with other systems
Integrate with JIRA issue Tracker
Link your code reviews directly to your JIRA issues
There are several aspects to the JIRA and Crucible integration. Each link below will take you into the details of each.
Create Reviews from inside of JIRA:
Learn how to create reviews from JIRA here
Associate and create JIRA issues for your reviews:
Integrate with your IDE
Create and work with reviews in Eclipse, Intellij, and Visual Studio
Using the free Atlassian IDE connector you can create, work with, manage, and monitor all your Crucible reviews directly from Eclipse, Intellj, and Visual Studio.
Some highlights include (this is a sample from the Eclipse Connector):
Below are the highlights of viewing and acting upon Crucible reviews within Eclipse.
Tips and Suggestions
Get reviewing quicker with these suggestions
Unleash the flexibility of Crucible by configuring it exactly to your needs. (click to expand)