Getting Started

CRUX comprises two parts:

The CRUX dashboard is integrated within Code Browser and provides a way to
publish, view, and respond to code reviews (CRs).

The CRUX CLI allows you to create and update code reviews from the command-line.

Installing the CRUX CLI

For information about installing and using the CRUX CLI, see Getting Started in the
CRUX CLI Guide.

If you are on a Cloud Desktop, you can skip this step, as the CLI will be
automatically available as part of the Cloud Desktop environment.

Basic usage
cd into a Brazil package you want to review changes to.

Stage your changes and commit to your repository:

git add paths_to_add

git commit -m "commit message"
Run cr.

Follow the URL it gives you.

Fill in the fields for description and reviewers.

Click Publish Review.

Running cr -h will give you all the options that are supported by the CLI.

Examples
CLI examples
Reviews just the latest commit:

cr --parent HEAD^
Updates a review with this range of commits (exclusive:inclusive):

cr -r CR-21354 --range efb4b3e:d6a7800

Reviews specific commit ranges for two packages:

cr --include "MyService[7f07509:a261b4a],MyServiceModel[HEAD^]"
Any tree-ish can be used, including branch names for defining ranges:

cr --include "MyService[baseBranch:myBranch]"
review multiple packages:

cr --include "<Package Name>" --include "<Package Name>" ...

Alternatively, if you don’t like typing “–include” for each Package…:

cr -i "<Package Name>" -i "<Package Name>" ...

Updates a review with multiple packages:

cr -r CR-12345 -i "MyService[7f07509:a261b4a],MyServiceModel[HEAD^]"
Reviews just the latest commit and append it to existing CR:

cr -r CR-12345 --parent HEAD^

If the old CR is deleted/closed and command cr still tries to attach to the old one
but fails, use:

cr --new-review
UI examples
Here is an example CR: https://code.amazon.com/reviews/CR-15521/revisions/1

Here is a user’s dashboard, incoming reviews: https://code.amazon.com/reviews/to-

user/haakon

Incoming reviews for a POSIX group:

https://code.amazon.com/reviews/to-entity/posixg/codex

Incoming reviews for a Team: https://code.amazon.com/reviews/to-entity/team/codex

See also
Using the CLI in the CRUX CLI Guide

Merging
EasyMergeService is the merge service that enables CRUX (code review tool for
internal Amazon developers) to merge code into a repository in GitFarm via Fast
Forward Merge, 3-Way Merge and Squash Merge APIs.

Merge options
Once you have all the approvals that you need and click on the Merge button, you
can choose one of the following merge types, depending on whether your commits are
fast-forwardable or not:

For fast-forwardable commits, you can choose Fast-forward (default), Squash or

Three-way merge.

For non-fast-forwardable commits, you can choose either Rebase (default), Squash or
Three-way merge.

Additionally:

If the tip commit of your local branch (source) in the CR is behind the tip commit
of the remote branch (destination), then you can merge your commit using Squash or
Three-way merge.

You can choose a different merge type per package in the CR.

You can edit the commit message for the squashed and three-way commits if the
number of commits for that package is more than one (1).

You can squash all your fast-forwardable commits into one by using the Squash merge
option.

You can use the Three-way merge option to create a merge commit (previously the
only option for non-fast-forwardable commits).

Fast-forwardable versus non-fast-forward commits

Fast-forwardable commits
At the time of merging your commits on CRUX, if the history of your local branch
(source branch) is the same as the git history of the remote branch (destination
branch) that you are merging to, then those commits are fast-forwardable.

In other words, there is a linear path between your commits on your local history
and the remote branch.
Non-fast-forwardable commits
At the time of merging your commits on CRUX, if the history of your local branch
(source branch) is not the same as the git history of the remote branch
(destination branch) that you are merging to, then those commits are non-fast-
forwardable.

In other words, if the remote branch history has changed because someone else
pushed new commits before you attempted to merge your commits, then your commits
have become non-fast-forwardable.

Merge types

Fast-forward merge
If the commits are ref:fast-forwardable <concepts-fast-forwardable-commit>, then
the commits will be applied in order directly at the tip of the destination branch
without the need for a merge commit. This is known as a fast-forward merge.

When doing a fast-forward merge, authorship of each commit in the CR is preserved.

See Preserving author / committer information for more information.

Squash merges
A squash merge will attempt to merge all of the commits in the CR into a single
commit. It is similar to using git rebase or merging with the --squash option, but
there are differences you should be aware of.

If the individual commits to be “squashed” in a CR have the same author, then the
resulting squash commit will be authored by that person. Otherwise (if they have
different authors), the author of the merge commit will be the user who’s
performing the Merge. See Preserving author / committer information for more
information.

Rebase merges
A rebase merge will rewrite the commits in your CR on top of the destination
branch. This allows for a cleaner, more linear commit history than a 3-way merge.
Squash merge also accomplishes this, but rebase allows multiple commits from a
single CR to be preserved.

Three way merges

A three-way merge is what we previously referred to as With a merge commit. It
takes all of the commits as-is and merges them together using an additional commit
known as a merge commit.

In a three-way merge, authorship of the individual commits in the CR is preserved,

but the merge commit itself is authored by the user who’s performing the Merge. See
Preserving author / committer information for more information.

Preserving author / committer information

The goal of EasyMergeService is to ensure that the behavior of our merge APIs is
similar to how git handles squashing and creating a merge commit when you run it on
your command line interface. In all cases, the committer is the requester of the
merge. However, the author of the changes can vary depending on the type of merge
request requested and author(s) present in the CR commit(s).
If it’s a fast-forward merge, then the author = author of the commit(s).
EasyMergeService does not change the commit SHAs.

If it’s a squash merge, then:

If all commits have the same author, then author = author of the commits.

If all commits have different authors, then author = requester of the merge.

If it’s a three-way merge with a merge commit, then the author = requester of the
merge.

Known limitations

Squash merge: how it differs from a rebase

A squash merge is similar to a git rebase only if you have a single commit for the
package:

For a CR with package that has a single commit to be reviewed, if the commit is
non-fast-forwardable, then the default merge option is squash-merge. If this option
is chosen and merged, the end result on your remote branch would be the same as it
would be in case of a rebase.

If you have multiple commits for that package, those commits will be squashed into
one single commit, before being merged to your remote branch.

No transactional merge: Some packages can fail while others succeed

This is as per CRUX & GitFarm design. GitFarm is designed to treat packages
independently even if a code review is raised for a multi-package CR (see GITFARM-
1204 ). The merges are not pre-flighted to make them atomic.

EasyMergeService APIs are synchronous and stateless, but CRUX will make async
merge requests for each package. The corresponding API will merge these packages
independently and return the response to CRUX. If some of these packages fail, they
cannot stop the rest of the packages from being merged. If the failures are not due
to merge conflicts, they can be retried immediately.

Dry-run merge: no option exists to show the merge result before the actual push
We do not support dryrun merge capability because:

GitFarm does not support that natively.

References in GitFarm cannot be deleted, resulting in adding more and more data to
the repository on each revision.

We would also end up spending a considerable amount of time to execute the merge
workflow on every revision to mostly get the same result as performing the actual
merge.

To avoid a slow merge workflow for customers, we decided the best approach for now
is to give the option to merge and report in case of failures.

CRUX Rules: EasyMerge does not automatically re-run a dry-run build before merging
squashed or 3-way merge commits
EasyMergeService does not re-run analyzers (for example, a dry-run build) before
merging the updated commit. EasyMergeService APIs are synchronous and stateless. As
a result, multiple dry-runs every time we attempt merging can cause too much
overload on the build requests, give rise to latencies and starve merge requests.

The principle is that your pipelines should have enough guardrails to prevent a
malicious commit from getting pushed to production. CRUX offers additional CRUX
rules that intends make this process easier and re-runs CRUX rules for every new
revision.

If you are really concerned about your build failing post squash or three-way merge
on the UI, we recommend you rebase locally and send a new revision. There is
ultimately no foolproof way to ensure every single commit that you merge will
successfully build on your pipeline despite the dry-runs.

Merge CR on top of another unmerged CR: cannot merge a commit whose parent is not
on the destination branch
Let’s say you have two commits, commitA --> commitB (commitA is the parent of
commitB). You created CR-A for commitA and you created another CR-B for commitB
using cr --parent HEAD. Then you cannot merge the CR-B because CR-A has not been
merged yet and as a result commitA is not on the destination branch yet. Since
these commits are linear, they will end up being fast-forward merged to the
destination branch resulting in an unreviewed commit being pushed.

CRUX will instead block merge with the error message:

The parent (base commit) of the commit(s) being reviewed is not found on the
destination branch. Please rebase locally.

See The parent (base commit) of the commit(s) being reviewed is not found on the
destination branch; Please rebase locally for info about responding to this error.

See also
Merging Code Reviews

Troubleshooting Merges

Creating a Code Review

Code reviews are created using the CRUX CLI. You can create code reviews for any
packages in a Brazil workspace. However, avoid creating reviews across multiple
Brazil workspaces, which can cause issues. Code reviews can also be created for any
GitFarm repositories that are located on your host.

Note
CRUX is only available for GitFarm and is not supported with any other source code
management system.

General procedure
To create a new code review (CR) with CRUX:

Run the cr command from the git root where a code change is committed and follow
the output link. If you have more than one package in your workspace that you’d
like to have in the same review, then run cr from the src directory and use the --
include option to add each package individually, or the --all option to include any
package with un-pushed commits.

On the code review page, enter a summary and notes for the reviewers. Use
CommonMark to format the content and modify the description as required.

Individual commits and their descriptions are listed at Commits tab.

Reviewers can be added in the Reviewers tab. You can add individual users,
LDAP/POSIX groups, and Teams. When you publish this code review everyone listed
here will be emailed. To notify a mailing list, use a Team with that list
associated with it. Otherwise all group members will be included individually.

Names of people, teams, and groups will be autocompleted. Click a name or highlight
it and press Enter to add that person or group to the review. Autocomplete searches
for teams/groups by name and people by name, login, and role and is case-
insensitive. Groups auto-generated from Teams will only show the Team.

If you need to edit the summary or notes, access the Details tab and click on
Actions ‣ Edit Details. Both summary and description will be available for update.

Once you are satisfied with your summary, notes, and reviewers you can click
outside of this dialog to go straight to the diff.

Clicking Publish Review will send notifications to all of the reviewers so they can
come see it and leave comments.

Creating a review for an arbitrary diff

Arbitrary diff code reviews are now supported.

At the moment you can create a code review for any diff compliant to any of these
formats:

Unified format

Git patch format

For more information please refer to the blog post.

If you are using the diff tool, you must specify the number of lines of unified
context. To get the full context (required by CRUX) specify a number greater than
the number of lines in your file.

diff -U 1000 current.sql proposed.sql | cr --arbitrary-diff-create-personal-pkg -a

-

Adding Reviewers to a Code Review

Additional reviewers that are not specified as a CRUX Rule can be added to a review
from the Reviewers tab. You can specify as many individuals as you want as well as
the specific number of required reviewers from a group.

Reviewers can be marked optional or required. By default, reviewers are marked as

Required.

For individuals, click the Required switch to toggle its state. For groups,
increment or decrement the required number of Approvals.

Remove a reviewer by clicking the trash can icon.

Note
These actions can be performed by any user with permission to view the code review.

Send CR to an email list

You may prefer to use an email list for your reviewers. You can approximate this by
using a team with an associated email alias.
To add an email list as a reviewer:

Create a team .

Edit the team ownership information to set its email alias to your desired email
list.

Enter the team’s name as a reviewer on the CRUX code review.

Note
The email alias associated with the team must be configured to allow external mail
in order to receive emails from CRUX.

If all the packages in the review are publicly readable, all CRUX emails will be
sent to the team email alias rather than dereferencing all the team members.

Favorite reviewers
You can favorite both people and groups, and they will then show up for you to
easily add them to a review. Favorited groups also control what reviews will show
up on your CR dashboard.

Favorite a reviewer by clicking on the star next to its name.

Favorite a group by clicking on the star next to its name while viewing your groups
.

Suggested reviewers
Suggested reviewers are available in case you don’t know what individual should
receive a review. Some teams prefer reviews to go to the entire group, while others
prefer reviews to go to an individual. It is common to “cc” a group, but also
identify a user who is expected to review the code. Having a declared reviewer
makes it more likely you will get a response quickly, instead of waiting for
someone to self elect.

Suggested reviewers are simply a random subset of the people who have write
permissions on the package. This is not an editable list. (We should arguably push
this content behind a click / hover, as the most common case is to send CRs to
people that you know well.)

Cloning code locally

There are a number of different ways to clone code locally for verification or
review.

Cloning with cr-pull (recommended)

Cloning with the Brazil CLI

Cloning with generic Git commands

Cloning with cr-pull

A command-line tool that pulls the changes from a code review into a new branch,
cr-pull, is available when you install CRUX with Builder Toolbox.

You can use cr-pull to clone changes into a new Brazil workspace or an existing
one:

Create a new Brazil workspace with the CR contents:

cr-pull --create-workspace https://code.amazon.com/reviews/CR-12345/revisions/3
Get the changes in your current Brazil workspace:

cr-pull CR-12345:3
See the documentation for cr-pull or type cr-pull --help for more information.

Cloning with the Brazil CLI

Use either of the following techniques within a Brazil workspace on your Cloud
Desktop:

Create a new repo in your workspace:

brazil ws snapshot clone snaphot_id

Check out code in an existing repo in your workspace:

brazil ws snapshot checkout snapshot_id

You can find the snapshot_id on the Commits tab of a review (looks like
"username/2010-01-02T03-04-05").

See the Brazil CLI Guide for more information about brazil ws snapshot.

Cloning with generic Git commands

To clone code from a CR using generic git commands, you can either:

Create a new repo in your workspace:

git clone ssh://git.amazon.com/pkg/pkg_id/snapshot/snapshot_id -b head

Check out code in an existing repo in your workspace:

git fetch ssh://git.amazon.com/pkg/pkg_id/snapshot/snapshot_id head \

&& git checkout FETCH_HEAD

Merging Code Reviews

Merging a code review (CR) merges your source branch into the destination branch.
CRUX determines the best merge type to use or you can select a specific merge type
during the merge process. For details about each supported merge type, see Merging.

Note
Only users in the source code permission group for the source packages in a CR can
perform a merge operation.

Perform a merge
A CR can be merged once it has received the required number of approvals and has
passed any configured CRUX Analyzer rules (such as Dry Run Build, InfoSecScan, and
so on).

Open the CR you want to merge (https://code.amazon.com/reviews/REVIEW-ID).

Click Merge. The Merge request page displays and shows all packages that are going
to be merged. Each package must report a Ready to merge status.

The Merge request page with a single package ready to be merged

Use the default merge type, or click Edit to choose a different merge type and
click Save. See Merge types for additional details.
Click Merge all packages to merge the CR. If the source branch can be merged to to
the destination branch, then the merge is completed. If there is a problem merging
the the source branch, then the merge fails and a message indicates the issue and
provides possible solutions.

Perform an override and merge

In exceptional cases, you may need to merge changes when all review requirements
have not been met.

Important
This is not intended as a common workflow, and you are required to enter a
justification for the override.

You must have write permissions on the package to Override & merge.

Open the CR you want to merge (https://code.amazon.com/reviews/REVIEW-ID).

In the Actions dropdown menu, select Override & merge.

The Action menu with the Override & Merge operation highlighted.
You must provide a plaintext reason for the override before the Continue button
activates. If an analyzer on your code review has FAILED, you may also need to
select one of several override feedback categories.

The override modal view contains a dropdown to select a Coverlay override category.
Select Continue to proceed to the Merge screen.

Merge your changes using the options provided. All reviewers will be notified that
you used the override and the reason you gave.

Preventing merges
In some cases you may want to prevent commits from being merged, even when they’ve
received the required number of approvals, such as when you are waiting for a
particular condition / launch before merging the changes.

If you are the author of the code review:

On the Details tab there is a checkbox labeled Allow reviewer to merge (pull
requests)?

If you uncheck this box, reviewers will not be able to merge your changes using
CRUX. You can change this box at any time, even after a CR is published.

If you are reviewing code:

On the Reviewers tab, add yourself as a required reviewer by typing your login in
the Add reviewer box.

Note
If you are already listed as a “watcher”, click this badge to flip yourself to be
“required” instead.

Your approval will have to be overridden for anybody else to merge the change.

Away-team merge permissions

A common pattern for away-team contributions is to only allow merging through a
CRUX code review. In this case the host team retains Can write GitFarm repository
permissions on the package, but the away-team is granted limited permissions (Can
approve GitFarm repository).

To assign a team permissions to merge using CRUX only

Enable the permission template:

Go to Bindles and open the Bindle to which you want to assign permissions.

Under Permissions, choose + Add.

In the Grant New Permissions window, choose Permissions Template.

Select Allow CRs to be merged in CRUX.

Choose Next step and then Submit.

Grant can approve repository permissions to the away-team:

In the same bindle, choose + Add again.

In the Grant New Permissions window, choose Custom Permissions.

In the Choose type field, select Team.

In the Team name field, enter the name of the away-team and select Next Step.

Choose the Gitfarm Repository Permissions category and select Can approve Gitfarm
Repository.

Choose Next step and then Submit.

The away-team should now be able to merge approved code reviews but will not be
able to git push changes directly.