Creating an Account

The signup process for Bitbucket is straightforward:

1. Navigate to https://bitbucket.org.

2. Locate and click the button labeled Get started (Figure 11-1). (There may be more than one. Either is fine.)

Figure 11-1. From the home page, locate and click one of the Get started buttons

You will be presented with the option to create a new account, or to sign up with your Google account:

1. Enter your first name and last name. These two fields are optional.

2. Enter your preferred username. Bitbucket will let you know if the name has already been selected.

3. Enter a secure password.

4. Enter a valid email address.

5. Select a plan. By default the free personal account plan is selected, which is appropriate for solo developers and very small teams.

6. Enable the checkbox confirming you are not a robot. You may also be presented with a CAPTCHA challenge if Bitbucket isn’t convinced you’re human.

7. Enable the checkbox for the privacy policy and customer agreement. Obviously, you should also click the links and read the agreements you’re signing.

8. When you have completed all of the fields, click Sign up to proceed (Figure 11-2).

9. You will be sent an email asking you to confirm your email address. Click the button Confirm this email address.

Figure 11-2. Complete each of the fields in the registration form and click Sign up

Your account is now set up and ready to use; however, to save some time later on, you should also add your SSH keys so that you can work with private repositories without having to re-authenticate yourself each time:

Complete the following steps to add your SSH key to your account:

1. Using the instructions in Appendix D, locate and copy your SSH public key.

2. Navigate to the dashboard for your Bitbucket account.

3. In the top-right corner of the Bitbucket website, locate and click the user icon.

4. From the drop-down list, click Manage account.

5. From the sidebar navigation, locate and click SSH keys.

6. Click on Add key. A modal window will appear.

7. Into the form field, Key, paste your public SSH key.

8. Click Add key.

Your SSH keys have been added to your Bitbucket account.

Creating a Private Project from the Welcome Screen

Immediately after creating your account, Bitbucket will redirect you to a welcome screen (Figure 11-3). This screen is always available at https://bitbucket.org/welcome.

Figure 11-3. After completing the registration form, you will be redirected to a Get started welcome screen

Create a new repository by completing the following steps:

1. Click on the bucket icon with the dashed outline which is labeled Empty.

2. Enter a name for this repository. For example, johannes.

3. Leave the checkbox This is a private repository selected.

4. Click Create. Your new repository has been created.

5. Click Done. You will be redirected to the repository setup configuration screen.

Once you have completed these steps, proceed to Configuring Your New Repository.

Creating a Private Project from the Dashboard

When you log into your Bitbucket account, you will be redirected to a dashboard summarizing your projects (Figure 11-4). From this dashboard you can get an overview of what is happening in each of your projects, and create a new repository.

Figure 11-4. The dashboard also gives a clear indication of how to create a new repository

If you are starting from the dashboard (this is also the home page when you are authenticated), create a new repository by completing the following instructions:

1. Locate and click the link to Create a repository. You will be redirected to the form shown in Figure 11-5.

2. Enter a name for this repository. For example, junio.

3. Optionally, enter a description for the repository.

4. Leave the default settings in place for the following:

   • Access level (checkbox should be enabled for this is a private repository)

   • Forking (drop-down menu should be set to Allow only private forks)

   • Repository type (radio button should be set to Git)

5. Optionally turn on Issue tracking, or Wiki pages. For personal projects I rarely turn these on because I’m typically just using Bitbucket as a remote backup for my code, and not as a project management tool.

6. Finally, locate and click Create repository.

Figure 11-5. The form to create a new repository also has some configuration options for sharing

Your new repository has been created, and you have been redirected to the repository setup configuration screen. Proceed to Configuring Your New Repository.

Configuring Your New Repository

You will be redirected to a setup page (Figure 11-6).

Figure 11-6. Setup instructions are available for GUI, and command-line (new projects, or existing projects).

Assuming you have been following along in this book, you likely already have a local repository, or you know how to create one! I find the final set of instructions (Figure 11-7) most useful when setting up new repositories on Bitbucket.

To connect your local repository to the new repository on Bitbucket, complete the following steps:

1. Locate and click on the link I have an existing project. A set of additional instructions will appear on-screen

2. At the command line, navigate to a local Git repository. It’s okay if it is already connected to a different hosting system, you are allowed to have multiple connections to remote repositories.

3. Copy and paste the commands beginning with git from the instructions (Example 11-1).

git remote add origin https://[email protected]/gitforteams/junio.git
git push -u origin --all # pushes up the repo and its refs for the first time
git push -u origin --tags # pushes up any tags

Figure 11-7. Setup instructions to connect existing projects to Bitbucket.

You are now set up to work as a solo developer with a private repository. You can push your code changes to Bitbucket as frequently as you like. And, because it’s a private repository, you never have to worry about corrupting public history! If you do rebase a branch and Bitbucket stamps its feet and refuses to accept the new version of the branch, add the parameter --force to the command you were attempting:

$ git push --force

Working with a team? A more polite version is as follows:

$ git push --force-with-lease

We will be exploring the web interface in subsequent sections. In the meantime, you may find some value in looking at the options that are available to you. If you have already been working within GitHub or GitLab from the previous sections in the book, I think you will find a lot of the options are quite familiar.

Exploring Your Project

Once your repository has been pushed to Bitbucket, the project page will update itself from a set of instructions to a project browser.

If your repository has a file named README, this file will be displayed on the project home page. Figure 11-8 shows my project home page for the Git for Teams website.

Figure 11-8. The project home page displays a summary of the status of your site, as well as the contents of the file README

The following summaries are available from the project home page:

• Last updated date

• Language, if one is set

• Access level (will be set to Admin if the repository is yours)

• Branches (click on the number above Branch for a list of all branches)

• Tags (click on the number above Tags for a list of all tags)

• Forks (click on the number above Fork for a list of all public forks)

• Watchers (click on the number above Watcher for a summary of accounts who are following this repository)

• Recent activity (visible in the right sidebar; includes recent commits, and merged branches)

The left sidebar has the following icons (from top to bottom):

• Link to the project home page

• Quick actions (includes clone, create branch, create pull request)

• Overview (appears to be the same content as the project home page)

• Source (a list of all files in the repository)

• Commits (the logged history for this repository)

• Branches (only available if you have pushed more than one branch to the project)

• Pull requests (irrelevant for personal projects)

• Downloads (provides a list of zipped packages of the current branch; you may also add untracked binaries for your project here)

• Settings (includes access details, repository name, integrations)

At the bottom of the screen there is also the option to expand the icons to display a text label for each of the icons. Once you’ve expanded the sidebar, you can collapse it again by clicking the double arrows (Figure 11-9).

Editing Files in Your Repository

Bitbucket allows you to edit text-only files from within its web-based text editor:

1. Click on the sidebar link Source.

2. Navigate to the page you want to edit.

3. Locate and click the button Edit. A text editor will appear (Figure 11-10, or Figure 11-11 for the project README file).

4. Across the bottom of the editor, confirm the Syntax mode, Indent mode, and Number of spaces (not available for all file types) are correctly set.

5. Edit the file to make the necessary changes.

6. Locate and click the button View diff.

7. Confirm the changes made are complete, correct, and do not introduce unwanted spaces.

8. Locate and click the button Commit. A modal window will appear (Figure 11-12).

9. Enter a commit message. You will need to add your own formatting. The first line should be a terse description not longer than 80 characters. Subsequent lines should provide more detail.

10. Locate and click the button Commit.

Your changes have been saved to the repository on Bitbucket.

Figure 11-9. Project sidebar expanded

Figure 11-10. In-repository text editor

Figure 11-11. Project home page editor

Figure 11-12. Add a message that describes the changes you have made to the project home page

With your changes saved to Bitbucket, your local repository will now be out of date. You will need to update your local repository. Because the respository is entirely your own, it is appropriate to pull the changes into your local copy without review (Example 11-2). Assuming you have followed the instructions outlined in this section, the work has been completed in the main branch for the project, which is most likely to be master.

$ git checkout master
$ git pull --rebase

The changes should apply cleanly. If, however, you end up with a conflict, refer back to Chapter 6.

Your local repository is now up to date.

Project Documentation in Wiki Pages

To begin collaborating with others, it can be as simple as granting repository access to another Bitbucket account. Hold up, though! Before you go jumping into a new relationship with a new developer, you should invest some time into stating how you would like to work. These steps should be documented, and they should be steps you yourself are willing to use. Fortunately, wiki pages on Bitbucket are much easier to edit than stone tablets, so you should consider your documentation to be a starting point, not the final word.

To enable wiki pages for your project:

1. Locate and click the settings cog for your project.

2. Locate and click the link Wiki settings.

3. Change the settings from No wiki to Private wiki (Figure 11-13).

4. Locate and click Save.

Wiki pages are now enabled for your project. A new icon will appear in the sidebar (Figure 11-14).

In Bitbucket, wiki pages are also repositories which you can download and edit locally. Documentation is included on the welcome page for your wiki (Figure 11-15). At the top of each wiki page is a breadcrumb trail. By clicking on the name of the project, you will be redirected to a list of all wiki pages for this project.

The editor for the wiki pages is a typical toolbar for Markdown files (Figure 11-16).

Figure 11-13. Enable a private wiki for your project

At a minimum, you should document the following for your project:

• Branch conventions

• Step-by-step instructions for submitting new work to the project

• Step-by-step instructions for peer reviews

• Deployment instructions, including who to email, and copy/paste email templates

Figure 11-14. The Wiki icon appears in the project sidebar

Figure 11-15. The default page provided for a Bitbucket wiki

Whenever you think there is a possibility for people to have different opinions, or where there’s a possibility a person could forget a step, you should have documentation. It doesn’t need to be long, but it does need to be correct. Check it regularly if your team likes process hacking. It’s possible the team has found an even more efficient way to do something that is not recorded in the documentation.

Figure 11-16. The Markdown editor for wiki pages

Tracking Your Changes with Issues

Issue tracking is another form of documentation. Although issues are much more ephemeral than wiki pages, capturing the information in a ticket provides the direct link from the business value, or rationale for building a feature, to the development tasks that are happening in code.

To enable the issue tracker, complete the following steps:

1. Navigate to your project repository.

2. Locate and click on the Settings icon.

3. Locate and click on the link Issue tracker settings.

4. Change the form option from No issue tracker to Private issue tracker.

5. Optionally, enter a new issue message.

6. Locate and click the button Save.

As you can see in Figure 11-17, I have added a default message for all new issues in the field New issue message.

The message reminds people to follow the Agile convention of Card, Conversation, Confirmation. This text will appear above the new issue form. Your team may have a different format they prefer to follow. Another format I’ve worked with and quite liked uses the headings: QA Test; Rationale; Details.

Figure 11-17. Enabling the issue tracker, and adding a default message for new issues

Issue tracking will now be enabled for your project (Figure 11-18).

To create a new issue, complete the following steps:

1. In the project sidebar, locate and click the icon Issues.

2. If this is your first time accessing the issue tracker, you will be directed to a welcome screen. Click Create your first issue to continue. If it is not your first time, you will be redirected to the summary page for all issues. From this screen, locate and click the button Create Issue. You will be redirected to an issue creation form.

3. On the new issue creation form (Figure 11-19), add a title and a description for your issue. The default values for Assignee, Kind, and Priority may be appropriate.

4. When you have described your new issue as best as possible, click the button Create issue.

Figure 11-18. The Issues icon now appears in the project sidebar

Your issue has been created (Figure 11-20), and is available from the Issues icon in the sidebar of the project. You are now ready for someone to begin work on this issue. First, though, you will need to grant access to the project so that you don’t need to complete every ticket yourself.

Figure 11-19. New issue creation form

Figure 11-20. Issue summary page

Shared Access

If you are working with a team of very trusted developers, you may choose to have them all commit into the same repository, and maintain a convention of which branches should be used for what purpose.

To grant a developer access to your repository, complete the following steps:

1. Navigate to Settings → Access management.

2. In the field labeled Users add the Bitbucket username or email address for the developer you want to add.

3. Change the access level from read to write.

4. Click Add.

Repeat these steps for each developer you would like to share this repository with. Developers will be able to do everything except administer the project. You’ve got your documentation in place, right? Because the only things holding this project together right now are the social conventions you’ve documented and have agreed to follow rigorously yourself.

Per-Developer Forks

As your team grows, you may want to prevent some parts of the team from having direct write access to the repository. Perhaps you would prefer if only the QA team were allowed to write to the main repository. In this case, developers will need to create a fork of the project first, and submit their work through a pull request.

Complete the following steps to create a fork of the project:

1. Locate and click the Actions icon in the project sidebar. These are the three dots directly below the logo.

2. Click on the link labeled Fork.

3. You will be redirected to a repository creation screen that very closely matches the one you saw when you were first creating your own Bitbucket repository. On this form it is acceptable to leave all of the defaults in place.

4. Optionally disable the Wiki and Issues options. You should use the main project repository to track this information.

5. To complete the process, click Fork repository.

You are now ready to create a local clone and begin your work:

1. Click the Actions icon in the project sidebar.

2. Select Clone. A modal window will appear.

3. From the pop-up window, select and copy the command line instructions.

4. At the command-line, navigate to the directory where you would like to place your copy of the cloned repository.

5. Paste the command provided by Bitbucket. The repository will begin downloading.

Once the repository has downloaded, you are ready to create a new branch and begin working on your ticket.

Limiting Access with Protected Branches

If you have worked with Subversion, you may have been quite surprised when you came to Git and found virtually no access controls. Instead of building in this functionality, Git has built in the ability for you to build your own access controls through hooks. These hooks allow you to script a response before or after a commit takes place, or before or after a push to a remote repository takes place. If you are hosting your own Git repository, you might think to take advantage of these hooks, but if you have become accustomed to using code hosting systems, you may not have known about this functionality. (And even if you did, it’s not necessarily something that you would have thought to script if you were just learning the basics of Git.)

Fortunately, Bitbucket has done the work for you. Through the web interface, you are able to grant write access per-person or per-team. In Chapters 2 and 3, you worked through your governance strategy with your team, and perhaps also your branching strategy. I won’t cover that again here. You should go back and review those chapters if you aren’t sure how you might want to take advantage of these access control options.

Previously you learned how to grant access to an entire repository. In this section, you will learn how to refine this access per-branch. Before proceeding with this section, ensure you’ve given repository access to the developers you want to work with.

To limit branch access, complete the following steps:

1. Navigate to Settings → Branch management.

2. In the first field under the heading limit pushes to specific users and groups, enter the name of the branch you want to limit control to; in the second field, enter the name of the person who should be allowed to update files in this branch.

3. Click the button Add.

The ability to push code to this branch has now been limited from all people except the person listed. Figure 11-23 shows that once you have added a person, you are welcome to add more.

Figure 11-23. Prevent others from pushing code to a branch

From the same configuration screen, Bitbucket also gives you the option to prevent the deletion of any branch, or prevent history rewrites on any branch. Although these two options are of less interest to you now that your team knows how to safely work with Git, you might need them “for a friend.” (It’s okay, I understand. And so does Atlassian, which is why it built you these two nifty features.)

Once implemented, an error will be returned if someone tries to perform a restricted action. Example 11-3 shows an example of what happens when I tried to delete a protected branch named master.

$ git push bitbucket master --delete
remote: permission denied to delete branch master
To [email protected]:emmajane/gitforteams.git
 ! [remote rejected] locked (pre-receive hook declined)
error: failed to push some refs to '[email protected]:emmajane/gitforteams.git'

If you do decide to implement access controls, make sure you clearly communicate these restrictions to your team. This will help to avoid absolute frustration by developers who cannot figure out why they can’t push their code to the project repository. You don’t need to provide lengthy tomes no one will read, but you do need to give people the rationale for why decisions were made, and any gotchas that make your system a unique and special snowflake to work with.

More information about Branch management is available from Bitbucket. You may also be interested to read Atlassian’s overview of working with Git’s hooks.

Submitting a Pull Request

After completing your issue-specific work in your ticket branch, and pushing your code to the server, you are ready to issue a pull request to have your work incorporated into the main project repository. The interface options will vary slightly depending on which access control method you’ve chosen. The basic process, however, is as follows:

1. Locate and click the sidebar icon Pull requests.

2. Locate and click the link Create pull request. A new form will appear for your request (Figure 11-24).

3. Your current repository will be located on the left. From this option, select the branch that has the change you would like to have incorporated into the main project.

4. The destination branch is located on the right. If your repository is a fork, you will be able to choose the destination repository as well as the destination branch.

5. Add a title, and description for your pull request. Ideally, your description should reference the issue you are aiming to close.

6. If you would like someone specific to review your work, you can enter his or her name into the pull request.

7. You can optionally have Bitbucket do a little maintenance for you and delete the ticket branch after the pull request has been accepted and the ticket is closed.

8. Finally, when the form is complete, click the button Create pull request.

Figure 11-24. The pull request creation form

As a developer, you must now wait for your work to be reviewed and accepted into the project, or kicked back with requested updates.

Accepting a Pull Request

Once a pull request has been submitted, it’s up to a reviewer to decide if the proposed changes are worthy of inclusion in the main branch. Chapter 8 covered the review process in detail. The pull request summary page allows reviewers to comment on the work that is being proposed. The conversation may result in the pull request being updated, or it may confirm the work is complete, correct, and ready to be incorporated into the project.

Assuming there are no conflicts, you will be able to accept a pull request by clicking the button Merge from the request itself.

If, however, there are going to be merge conflicts, the process is a bit more complicated. Often the best person to resolve a conflict is the developer of the new code that is being added. Typically what happens is that the code has become stale while waiting for its review. Have the developer update her ticket branch so that it includes the latest changes from its parent (or source) branch:

$ git pull --rebase=preserve

If the person who submitted the pull request is not available to resolve the merge conflicts, you may need to complete this step yourself. Fortunately, Bitbucket gives you some copy-paste commands for downloading the ticket branch and resolving the conflict.