Welcome to Crucible 101, an introductory guide to Crucible and a tour of the most interesting Crucible features. Use this page to guide your evaluation process or quickly get up to speed with Crucible.
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 set up Crucible and you will be ready for your first code review in no time. Setting up Crucible takes less than half an hour.
Install
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.
- Navigate to the
bin
sub-directory of your installation directory. Type/executerun.bat
(under Windows) or./run.sh
(under Linux) to launch Crucible. A Crucible console window will appear, listing the startup progress. Give it a few minutes to complete. - 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
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 any of the supported SCMs listed on the Supported Platforms page.
If you use Crucible with FishEye, FishEye allows advanced searching and rapid access to repository contents. Note that your Crucible evaluation license enables FishEye.
See the configuration documentation for more.
Set Up Your Crucible Project(s)
Your Crucible instance must have at least one project, in a fresh install this is 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.
Crucible projects let you organise your reviews into logical groups, however they also 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)
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)
- If you already have a JIRA server set up, you can set up integration between your JIRA server and Crucible. Once established, activity on relevant JIRA issues will appear in the Crucible activity stream. JIRA issue keys will also be hyperlinked and 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.
Setup Complete!
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.
Creating Reviews
Reviewing Quick Start
![]() |
If you are getting familiar with Crucibles structure - roles, workflow and parts of a code review please refer to the following document before moving forward. |
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
Pre commit
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.
Post commit
- 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
- 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
Comments turned into defects
- You can easily highlight defects in the code under review by click on the 'Defect' checkbox when commenting.
- All 'Defects' can be classified with a priority
- Crucible tracks the time you have spent on each file in a review and also your progress through the review.
Context Windows
Try hovering your mouse over the following links in Crucible to see the context windows:
- Crucible usernames,
- JIRA Issue Keys (when using JIRA; see the documentation).
- CSIDs (when using FishEye; see the documentation).
Activity & People
Crucible adds a modern social web dimension to the usually impersonal data stored in your Source Code Management (SCM) repository.
Activity Streams
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.
People Lists
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.
People Pages
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
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
In Crucible, you can add the following items as favourites:
- Reviews,
- Review Comment Threads,
- Projects,
- People,
- Changesets,
- Files or Folders,
- Repositories.
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
- Configure your Email preferences.
- Check out the handy Blocker report and JIRA Blocker Reports. Every now and then, someone in the team can become a bottleneck in the review process. The review blocker reports help by identifying team members that have a lot of reviews waiting in their inbox.
- Configure your personal dashboard and set up RSS feeds.
Search
Search Options
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.
Quick Nav
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.
Advanced Features
Crucible will allow you to go beyond commenting on source code. Iterative reviews, reports and auditing, plugins, JIRA integration, IDE integration, and much more.
Iterative Reviews
Files are always up to date
- 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
- When adding files to a review, you can also review multiple revisions of a file.
Reporting
Plugin Reports
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
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
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:
Tips and Suggestions
- Wiki markup in your review comments - this is a way to make your comments stand out.
- Keyboard shortcuts - Keyboard shortcuts can help save some time on creating, editing, and working with reviews.
Configuration Tips
- In Crucible, you can set configure defaults per-project for review duration, review objectives and reviewers.
- Crucible allows you to customise your own permission schemes.
- Crucible lets you disable the moderator role, for lightweight, faster peer-to-peer reviews.
Thanks for taking the time to evaluate Crucible using this guide. To help continue your journey, our support staff are always ready to answer your questions in the Crucible Forum, or solve specific problems at our support portal http://support.atlassian.com.