Navigating GitHub

Version control with Git takes on a distributed nature. The code resides on each local computer where the code base is being worked on, as well as on a central remote point where every individual who wishes to work on the code base can obtain it. GitHub is one such central remote point. GitHub hosts repositories and enables users to obtain, alter, and integrate changes to a code base through Git:

Figure 1.1: Relationship between the Development environment and GitHub

Exercise 1: Setting Up a GitHub Account

To capture how GitHub serves as a hosting utility, we shall now proceed to explore the features that are offered by exploring the user interface:

1. Enter your user details, as shown in the following screenshot, and press the Sign up for GitHub button:

   Note

   You'll be requested by GitHub to verify the email address that you used when signing up. Please check your email for instructions.

   

   Figure 1.2: The GitHub home page

2. Choose a plan and set the preferences that best indicate your utilization of GitHub as seen in the following screenshot:
   

   Figure 1.3: The welcome screen

   

   Figure 1.4: Registration details

3. With account registration completed, you should see the page pictured as follows:
   

   Figure 1.5: Account registration

4. To further configure your account, please select the right-most drop-down button and select the Settings option. The account settings should be listed, as pictured in the following screenshots:

Figure 1.6: Account configuration

Figure 1.7: Account settings

Outcome

You have successfully set up a GitHub account as a hosting utility.

We shall now look at using the Settings menu to enable two-factor authentication and create an organization.

Exercise 2: Utilizing Two-Factor Authentication

You'll need to have Google Authenticator installed on your phone. The app is available on Android and iOS.

To enable two-factor authentication on the account so that you have enhanced security, follow these steps:

1. Go to Settings and select Security.
2. Click the Enable two-factor authentication button and enter your password on the next prompt:
   

   Figure 1.8: Two-factor authentication

3. Select the method you wish to use to set up two-factor authentication.

   Note

   We shall use an app for this demonstration. The SMS option may not be supported for all regions.

4. Click Set up using an app:
   

   Figure 1.9: Setting up using an app

5. Download the recovery codes and store them in your preferred location.
6. Press Next to proceed to the next step.
7. On your phone, select Set up an account.
8. Select Scan a barcode to scan the QR code presented on your browser, as shown in the following screenshot:
   

   Figure 1.10: Scanning a barcode

9. Insert the six-digit code shown on the app into the text field below the label that reads Enter the six-digit code from the application and press Next:

Figure 1.11: Completed two-factor authentication setup

Note

With two-factor authentication configured for your account, you should be able log in using your password and the code provided by the app. You can configure your account to use a registered SIM card by using the callback SMS number option. Additionally, you can change your account to use SMS as the default login method for receiving the authentication code instead of the app. This can be achieved using the Delivery options.

Outcome

You have successfully configured two-factor authentication for your account.

Organizations

GitHub offers the ability to manage multiple projects and, by extension, repositories using a shared account that's referred to as an organization. Using an organization, you can arrange contributors in a project to reflect your organization's structure. This structure corresponds to the teams that work on the respective projects as well as the access rights assigned to the individual contributors on each team.

Organizations spur seamless coordination of work through the following features availed by GitHub:

1. Role-based membership. Three roles exist in role-based membership, that is, owner, billing manager, and member. Each personal account that is added to an organization can belong to one of the aforementioned roles. The owner role is the most superior and is used to conduct administrative procedures.
2. Repository level permissions. Teams or their respective members can be assigned read, write, or admin-level permissions to a repository. Each level dictates activities that the assigned members undertake, with a varying degree of limitations. The following diagram shows the three levels of permission, in order of increasing capabilities, that are available in the respective levels:
   

   Figure 1.12: Block diagram

3. Teams: These are members of an organization that can be grouped into teams, with the option of nesting the teams to match an organization's structure.
4. Multi-factor authentication: Organizations support the enforcement of two-factor authentication as well as business-specific single sign-on approaches such as Security Assertion Markup Language (SAML) and System for Cross-domain Identity Management (SCIM).

Exercise 3: Setting Up an Organization

To create an organization, you may convert your personal account to an organization or create an organization which you can then associate with your personal account.

1. On GitHub, go to Settings and select Organizations. Then, click New organization:
   

   Figure 1.13: Setting up the organization

2. Enter the organization's details, choose a plan, and click Create organization:
   

   Figure 1.14: Creating an organization account

3. Search and add users, or click Finish to conclude the process on the next prompt.

Outcome

You have successfully set up an organization for your account.

Exercise 4: Setting Up a Team

With GitHub organizations, you can, as stated previously, organize contributors in teams and manage permissions and restrictions at a team level and repository level.

To create a team under the versioncontrolgithub organization, follow these steps:

1. Go to https://github.com/.
2. On your left, you should find a drop-down menu with your username. Click on the dropdown to reveal the organizations that you belong to:
   

   Figure 1.15: Creating an organization account

3. Click Manage organizations and then click the versioncontrolgithub organization on the next prompt.
4. Click on the Teams tab on the organization's dashboard:
   

   Figure 1.16: versioncontrolgithub

5. Click on the New team button on the next prompt.
6. Set the team details and click Create team:

Figure 1.17: Creating a new team

Figure 1.18: Team home page

Outcome

You have successfully created a team under the versioncontrolgithub organization.

As seen from the preceding steps, a team can:

• Be utilized to manage pieces of work organized under repositories.
• Have members assigned to it to collaborate on specific repositories.
• Be assigned task-tracking boards under Projects.
• Have nested or child teams created under it. This can be achieved from the Team tab, which is shown in the preceding screenshot.

Marketplace

GitHub offers the ability to integrate applications with your account. These applications serve a range of roles such as continuous integration, code quality analysis, and dependency management analysis. Next, we shall set up Codacy for our accounts. Codacy is used to analyze code that's introduced into a project to identify areas of improvements where action can be taken before changes are merged.

Exercise 5: Setting Up Codacy for Accounts

Consider using the following text as the description text for the exercise.

To set-up Codacy follow the steps below.

1. Go to https://github.com/.
2. Click Marketplace on the top navigation bar.
3. Click Code quality from the categories list.
4. Click Codacy, which is listed on the right:
   

   Figure 1.19: Code quality

5. From there, click Set up a plan and Install it for free:
   

   Figure 1.20: Codacy setup

6. Click Complete order and begin installation.
7. Authorize the application by clicking the Authorize qamine button:
   

   Figure 1.21: Authorizing Codacy

8. Enter your password and click Confirm password to complete the setup process.

Outcome

You have integrated Codacy into your account for use in quality control of code.

Runtime Config

Git supports the configuration of runtime options. These options and/or values are used by other Git commands to dictate behavior. Runtime configurations are set using the git config command.

The git config command allows for the setting, retrieving, removal, and replacement of configurations. Git configurations are set in three levels, namely:

System wide configuration

These options are set in the /etc/gitconfig file. The presets specified in this category are used for all of the users on a computer.

To access these settings, you use the git config --system flag specifies that system wide configuration should be used.

User-specific configuration

These options are set in the ~/.gitconfig file. The presets provided here are used for the user account that is in use on a computer.

The user-specific settings are accessed via the git config --global flag specifies that user specific configuration should be used.

Repository-specific configuration

Repository-specific settings are set in the path_to_repository/.git/config file. The options set here are used at the repository level. An example of configuration here is the GitHub URL of a repository, which is set at this level.

These settings are accessed via the git config --local flag specifies that repository specific configuration should be used.

You may specify a specific config file using the -f or --file option.

Exercise 6: Setting User Credentials

To set up the user credentials for an account, follow these steps:

1. Launch the Terminal or command prompt.
2. Set the username by using the following command: git config --global user.name kifeh-polyswarm:
   

   Figure 1.22: Setting up a username

3. Set up the email by using the following command: git config --global user.email [email protected]:
   

   Figure 1.23: Setting up an email

4. List the configuration using one of the following commands:

git config --global --list
Or, git config --list , to fetch all the available presets

Figure 1.24: Setting up the user credentials

Outcome

You have successfully set up the user credentials for an account.

Removing Configuration

Using git config, we can remove configuration in the event that a change is required. The git config utility supports this by using the --unset option.

The syntax of the command is indicated as follows:

git config --global --unset [section_name].[section_variable]

Example

git config --global --unset user.name

The preceding command will remove the value set for the user's username.

SSH Configuration

To interact with a repository and/or conduct tasks on GitHub from your local environment, you need to assert you are who you say you are. Git supports this by using a combination of a username and password, or using an SSH key to authenticate a connection or requests made to GitHub from your local environment.

The use of SSH keys ensures enhanced security and averts the need to provide a username and password for each request.

Exercise 7: Setting Up SSH

To set up the SSH key for the account, follow these steps:

1. Launch the Terminal or command prompt.
2. Generate a SSH key using the following command:

   ssh-keygen -t rsa -b 4096 -C "[email_address]"
   Example: ssh-keygen -t rsa -b 4096 -C "[email protected]"

   

   Figure 1.25: Generating an SSH key

3. Specify the location where the generated key is to be stored. You may press Enter to instruct the key generator to use the default location:
   

   Figure 1.26: Specifying the storage location

4. Type a passphrase to secure the generated key as seen in the following screenshots:

Figure 1.27: Using a passphrase for security

Figure 1.28: Using a passphrase for security part 2

Figure 1.29: Generating the SSH key

The key is stored in the specified location, as pictured in the preceding screenshots:

1. Start the SSH agent using the following command: eval "$(ssh-agent -s)".
2. On macOS, edit ~/.ssh/config to enable the ssh-agent to automatically load keys and store passphrases in the keychain:

   Host *
   AddKeysToAgent yes
   UseKeychain yes
   IdentityFile [location_of_the_generated_private_key]

   Example: Host *:

   AddKeysToAgent yes
   UseKeychain yes
   IdentityFile ~/.ssh/version_control_git/id_rsa

3. Add the SSH private key to the ssh-agent.

   Note

   -K adds the passphrase to the keychain when a private key is added to the ssh-agent.

   ssh-add -K [location_of_the_generated_private_key]

   Example: ssh-add -K ~/.ssh/version_control_git/id_rsa

4. Add the public SSH key to your GitHub account. Go to https://github.com/, and then go to Settings as shown in the following screenshot::
   

   Figure 1.30: GitHub Settings

5. Click SSH and GPG keys as shown in the following screenshot::
   

   Figure 1.31: SSH and GPG keys

6. Click New SSH key and set a title for your public SSH key.
7. Launch the Terminal and copy the contents of the public SSH key to the clipboard using the following command: pbcopy < ~/.ssh/version_control_git/id_rsa.pub.
8. Paste the contents of the public key into the field under the label Key:
   

   Figure 1.32: SSH keys/Add new

9. Click Add SSH key to add the public key to your GitHub account.
10. Test that the SSH key has been set up properly by making a request to GitHub using the following command:

    ssh -T [email protected]

Figure 1.33: Testing the SSH key's setup

You have successfully set up the SSH key for the account.

Creating a Repository

Version control requires that the files and associated changes that need to be tracked are organized in a repository which is the unit that Git identifies as the candidate for source control. To commence a piece of work, we need to create a repository.

In this section, we shall explore two approaches that you may use to initialize a repository.

Exercise 8: Creating a Repository in a Local Environment

Initializing a repository locally entails using git init and mapping the local repository to its corresponding remote repository:

1. Launch the Terminal.

   a. On a Linux computer: Press Ctrl + Alt + T.

   b. On a macOS computer: Press ⌘ + spacebar, Type Terminal or iTerm, and then click the application logo to launch the Terminal:

   

   Figure 1.34: Launching a Terminal on macOS

   c. On a Microsoft Windows computer: Press Win + R on your keyboard to launch the Run window. Then, type cmd.exe and press Enter on your keyboard, or click OK on the Run window.

2. Create a directory for the application using the following command: mkdir abacus:
   

   Figure 1.35: Creating a directory

3. Change the working directory to the project directory using the following command: cd abacus
4. Initialize the repository using the following command: git init.
5. Go to https://github.com/
6. Click New repository on the left-hand pane on the page:
   

   Figure 1.36: New repository

7. Specify the name of the repository as shown in the following screenshot:
   

   Figure 1.37: Creating a repository

8. Click Create repository.
9. Click on the SSH button to obtain the SSH URL. This button is below the text that reads Quick setup - if you've done this kind of thing before:
   

   Figure 1.38: Quick setup

10. On the Terminal, specify the GitHub URL of the repository, that is, abacus:

    git remote add origin [repository_url]

    Here is an example: git remote add origin [email protected]:kifeh-polyswarm/abacus.git

    

    Figure 1.39: Specifying the GitHub URL

11. Add the file where we'll host the class that will host our code using the following code as seen in the following screenshots:

    mkdir -p src/lib

    touch src/lib/compute.py

    

    Figure 1.40: Hosting the code

    

    Figure 1.41: Hosting the code part

12. Prepare the files for the first commit using the following command: git add src/lib/compute.py
    

    Figure 1.42: Preparing the files for commit

13. Commit the files using the following command: git commit -m "Initial commit"

Figure 1.43: Preparing the files for commit part 2

Note

The -m option that's used with the commit command specifies the message we wish to use for a commit.

You can push the repository files to the repository on GitHub using the following command: git push -u origin master

Figure 1.44: Pushing to the GitHub repository

Outcome

You have successfully initialized a repository locally by using git init and mapping the local repository to the remote repository.

Note

The -u option that's used with the push command sets the remote branch of the remote repository that the local repository is linked to. This option is used to create a tracking reference between a local and remote branch. It enables you to run git push or git pull without having to specify arguments such as the branch name as shown in the following screenshot:

Figure 1.45: Pulling from Git

Exercise 9: Creating a Repository on GitHub

To start a piece of work, you may, instead of initializing a repository locally, create the repository on GitHub, after which you can then clone it locally:

1. Go to https://github.com/.
2. Go to your account's repository listing by clicking Your repositories and then click the New button as shown in the following screenshots:
   

   Figure 1.46: Your repositories

   

   Figure 1.47: New repository button

3. Specify the repository name and description:
   

   Figure 1.48: Creating a new repository

4. Click the Create repository button.
5. Retrieve the SSH URL:
   

   Figure 1.49: Quick setup

6. Clone the repository on your local environment using the following command as seen in the following screenshot:

git clone [repository_url].

Example: git clone [email protected]:kifeh-polyswarm/clone-demo.git

Figure 1.50: Cloning a repository

Outcome

You have successfully created the repository on GitHub, which you can now clone locally.

Navigating a Repository

GitHub offers features on a repository level. These features provide an outlook of work and progress on a repository by offering insights related to velocity, adherence to community standards, and utilization of a repository by the community.

Collaborators

GitHub supports adding and removing contributors to/from a repository.

Exercise 10: Adding and Deleting Contributors

To add or remove contributors from a given repository, follow these steps:

1. Go to a repository on your account, for example, https://github.com/kifeh-polyswarm/abacus.
2. Click Settings and then click on Collaborators:
   

   Figure 1.51: Settings tab location

   

   Figure 1.52: Settings part 2

3. Search for a user by their email address, username, or full name, for example, alex-magana as shown in the following screenshot:
   

   Figure 1.53: Adding collaborators

4. Select the resultant user and click Add collaborator as seen in the following screenshots:

   Note

   Once the user to whom you've sent an invite accepts the invite, they should be able to make contributions to the repository.

Figure 1.54: Accepting invitation

Figure 1.55: Repository home page

Outcome

You have successfully added contributors to a given repository.

Navigating Branches, Commits, and Insights (Contributors, Pulse, Forks)

Branches can be viewed and deleted in line with housekeeping processes. This can be done by going to the repository on your account, for example, https://github.com/kifeh-polyswarm/abacus. Next, you have to click the Forked 1 Branch button on the top bar to view a list of branches. Then, you should be directed to a page with an overview of the branches present on a repository:

Figure 1.56: Repository overview

Commits present the state of a repository at the time of their creation. You can browse a repository at a commit's point in history and explore files that have been altered by a commit. Then, go to a repository on your account, for example, https://github.com/kifeh-polyswarm/abacus and click the 1 commit icon to view the commits on a repository. In order to view file alterations on a commit, click the commit hash, for example, f4e4e8d as shown in the following screenshot:

Figure 1.57: Repository part 2

Then, to browse the state of a repository at a given point in time, click the double arrow icon. This can be found on the far right of each commit that's listed. Lastly, you can observe commits that have been organized in order of the respective contributors. This plays an imperative role of coordinating matters such as knowledge sharing across teams by leveraging the different strengths of the contributors. On a repository of your choice, click Insights and then click Contributors to view the contributors, along with details of the specific contributions that have been made as shown in the following screenshot:

Figure 1.58: Repository part 3

GitHub Etiquette

A certain decorum is expected of repositories and users in using Version control and collaborating on GitHub. This propriety ensures that contributions are carried out in an orderly manner and promotes constructive working environments that focus on delivering value.

GitHub provides a checklist through a Community profile that can be accessed through the Insights tab of a repository navigation as shown in the following screenshot as follows:

Figure 1.59: Community profile

Repository Names, Tags, and Descriptions

Take a look at the following definitions:

Names

A repository should bear a descriptive name that relates to the functionality an application seeks to deliver.

Tags

These are used for the purpose of identifying specific significant points on a repository's history, for example, software releases, Git supports the creation of markers, referred to as tags, to correspond to software versions.

Tags are of two types: lightweight and annotated.

Lightweight tags act as pointers to a specific commit. It only stores the reference to the commit:

git tag v2.5

Annotated tags act as pointers to a specific commit and additionally store information about the creator of the tag, the email, and date of creation:

git tag -a v2.6 -m "Support sdk version 3"

Tags shall be further covered in detail later in this book.

Descriptions

A repository description is required as a best practice. This serves as the first point of introduction and sets the basis on which a repository's functionality is understood.

Adding a Description

This is done by clicking the Add button to the right of Description on the Community profile and then adding the description and clicking Save:

Figure 1.60: Description entry

README.md

This document provides a brief on the project handled by a repository. It encompasses a getting started guide, references to wikis, and conduct and contribution guidelines.

Adding a README.md, CODE_OF_CONDUCT.md and CONTRIBUTING.md

This is achieved by clicking the Add button to the right of README on the Community profile. From here, you should add the necessary details and commit the changes:

Figure 1.61: Committing a new file

This file will be altered as we add features to our application throughout the book.

Then, click the Add button to the right of Code of conduct on the Community profile. Next, select a preferred code of conduct guide as follows:

Figure 1.62: Code of Conduct

Then, commit the document to your repository:

Figure 1.63: Committing a new file

Next, click the Add button to the right of Contributing on the Community profile. Lastly, you may commit the document and alter it to fit your project.

LICENSE

A license governs the utilization of an application by its users by dictating the obligations and responsibilities of the creator and user of a software application.

Licenses are applicable, for example, in averting a creator from indemnifying a user when an application is used contrary to its terms of use.

Exercise 11: Adding Licenses

To add the appropriate license to the document, follow these steps:

1. Click the Add button to the right of License on the Community profile.
2. Choose a preferred license. In this case, we shall choose the MIT License.
3. Click Review and submit once you have finished reviewing the document:
   

   Figure 1.64: MIT License

4. Commit the document. You can alter this document to fit your project.

Outcome

You have successfully added the MIT license to a given repository.

Wikis and Issues

Take a look at the following definitions:

Wiki

Wikis provide an avenue for documenting processes and guides for the usage of a certain piece of software.

You can use wikis to document conventions that should be applied in creating branches, reporting issues, and making feature requests.

To access and/or create wikis, use the Wiki button on the top navigation bar:

Figure 1.65: Abacus wiki

We shall use wikis to document best practices and conventions for the application we will be building in this book.

Issues

GitHub issues are suitable in reporting challenges or bugs that are encountered when using an application, as well as in making feature requests. Issues aid in tracking tasks that:

• Need to be undertaken as part of a products roadmap
• Respond to user requests and challenges reported, for example, bugs

To facilitate the filing of issues, we need to create templates that serves to ease the reporting process. You will need to click the Add button to the right of Issues template on the Community profile. Then, select the Bug report and Feature request templates. Lastly, preview and edit the templates if need be as seen in the following screenshots:

Figure 1.66: Abacus Bug report

Figure 1.67: Issue: Feature request

By clicking the Propose changes button and Commit changes thereafter to add the template to your repository, you will be able to file the issues request.

Raising an Issue

This is easily achieved by selecting the Issues tab on the top repository navigation bar:

Figure 1.68: Labeling issues and pulling requests

Then, click New issue to file an issue. On the next prompt, select the appropriate issue type, for example, Bug report. Lastly, you can provide details of your issue and click Submit new issue to complete the process, as shown in the following screenshot:

Figure 1.69: Issues: Bug report

Activity 1: Creating a Repository

You have been instructed to build an application that enables its user to order food from a restaurant and have it delivered. To commence this piece of work, you need to build the application while leveraging version control. You need to create a repository that will host the application. This repository will be used to track task completion and the deployment of the application.

To get started, you need to have the Git command-line tool installed on your computer. Additionally, you need to have an account on https://github.com/ and be logged into your account on GitHub:

1. Launch the Terminal.
2. Create a directory named [dine-in] for the application and navigate to the dine-in directory.
3. Initialize the repository.
4. Go to https://github.com/ to create a new repository with the name dine-in.
5. Obtain the HTTPS or SSH URL of the repository from GitHub.
6. Set the remote URL on the local repository:
   

   Figure 1.70: Setting the remote URL

7. Create a README file and a .gitignore file, both of which are going to be added to the index.
8. Commit the files and then push them to the remote repository:

Figure 1.71: Setting the remote URL

Outcome

You have successfully created a repository on your GitHub account with README.md and .gitignore files

Note

For detailed steps of this activity, refer to the Appendix section on page 272.

Logistics

Conduct a recap of the concepts that have been covered in this topic.