Setup VSCode and GitHub Integration on macOS

As you start using macOS X for your Microsoft Azure Data development, VSCode may be just one of the many development packages you want to set up, but it is one of the most important. With the setup, using Github as a code repository will make life easier, as many Azure repositories and services utilize Github.

What makes this difficult is that your integration will depend on which of the following authentication methods you use;

Straightforward GitHub Authentication, User ID, and PW
2 Factor, which is in addition to option 1
Are you a member of any organizations, such as Microsoft Docs

The following overview will cover various options you may face while setting up VSCode with GitHub integration.

Some developers prefer to use the command line with GIT, but I prefer to use GitHub and GitHub Desktop as my primary interface. Let’s install these two applications before tackling the integration.

Warning_: Every machine is different. This walk-through is provided as an illustration and covers a base machine install. No guarantee or warranty is provided or implied.

Note: This article assumes this is not the first application installation. Some screens shots will be displayed, but any steps with simple choices are provided as written detail.

Step 1 – Install GIT onto macOS X

Select the latest version from the main GIT Downloads website, and Download X.XX.X for Mac button in the iMac graphic.

This downloads the installer from the SourceForge website. You should see this in your browser download folder. The screengrab below shows how this looks in Microsoft’s Edge browser for the Mac.

Click the link to Open the file. On a Mac, when you click on a Zip file that contains multiple files, it will unzip into a folder matching the zip archive’s file name.

This shows the install package; click once to install. (On a PC, a double click, just a little difference between the two systems.)

This will bring up a warning message, which may differ depending on your security setup.

You have to click with the Control key depressed to bring up a dialogue that allows you to authorize and enable the macOS to open it.

This brings up an Open dialogue; select Open.

This brings up the option to “Open” or install the package.

Select Open. This brings up the installation dialogue. Follow the steps until the installation is complete.

macOS X will display a system dialogue and request your password to allow the installation. This is the OS, not the installation package asking for your password and permission !!!
This example is being run on a macOS based device with Touch ID. Your dialogue may be slightly different.

You should see this dialogue below when complete.

Now onto the next step.

Step 2 – Install GitHub Desktop onto Mac OS X

The steps to install GitHub Desktop follow the same general process as above.

Clicking the Download for macOS button will download a ZIP file to your download folder. The screengrab below shows how this looks in Microsoft’s Edge browser.

When you click on a ZIP file in macOS, it will unzip to a folder or file in the folder where the ZIP file resides, in this case, the Download folder, as shown below.

You may have to hold down Control to open the app, but I was able to click on the app in the Download folder, and the following dialogue came up.

The remainder of the dialogues are self-explanatory; follow along.

Further documentation on how to use GitHub Desktop can be found in the site’s documentation; GitHub Desktop Documentation

Step 3 – Install Visual Studio Code (VSCode)

Main Install

Using VSCode as your source code editor allows you to use the same editor across numerous platforms, Windows, Linux, and macOS while having direct integration with GIT (GitHub in our examples). This brings the ability to have a full code editor, which brings functions such as; syntax highlighting, code completion, code refactoring, and snippets. Features such as the ability to change the themes, keyboard shortcuts, and many configuration preferences allow you to create the editing experience you prefer for your workflow.

Installing VSCode is as simple as going to the VSCode portal and clicking download on the main portal.

This option will take you to the Getting Started page. If you get the following pop-up, which could be different depending on which browser you use, you can save a copy or run the installer directly after downloading.

As in the previous step, this will provide a ZIP file that will unzip the application in the download folder.

You will get a warning and have to hold down Control to open the app, but I was able to click on the app in the Download folder, and the following dialogue came up.

Holding down the Control key and clicking on VSCode will bring up the following dialogue. Select Open.

This then brings up a dialogue that you can use to open the application.

Once Open, you can copy the app from the Download folder to the Application folder, as shown below.

Step 4 – Configure VSCode

Rather than a full how-to on using VSCode, see the Getting Started page for more. This section will provide a brief interface walk-through in addition to reviewing the configuration of VSCode for Github.

C:\Users\styoung\AppData\Local\Temp\SNAGHTML3817533e.PNG

#	Item	Description
1	Menu Bar	Shows the changes that have yet to be checked into Source Control.
2	Code Edit Pane	Multi-tab edit window. Tag 11 shows the Split Pane, which allows you to open multiple code windows.
3	File Explorer	This option will expand the left pane to display the files and directories in the current working folder.
4	Search	Includes Search and Replace.
5	Source Control	This allows you to open up multiple tabs/code files in the same display.
6	Debug Window	Bring up the debug screen.
7	Extension window	This shows the Extension windows. Extensions are add-ins that provide additional functionality. Python is such an extension.
8	VSCode Settings	Various editor defaults and settings.
9	Terminal and Output message toggle	This brings up the Terminal split screen. Problems, Output and debug console are in this section.
10	Toast Style messages	Various messages will be displayed depending on the context you are in.
11	Open Tab Window	This brings up a callout menu that allows you to close all the currently open code windows or only those that are saved. (As an aside, if the 3 dots were vertical they are called a Kabob, Who knew!!)
12	Ellipse menu (Callout)	This brings up a callout menu that allows you to close all the currently open code windows or only those that are saved. (As an aside, if the 3 dots were vertical, they are called a Kabob, Who knew!!)

VSCode Configuration Screen

Step 5 – Setup and Connect VSCode to use GitHub on a macOS X

VSCode has numerous extensions, of which integration with GitHub is one of them. By selecting the Extensions icon, you can search and browse various extensions. We will step through the GitHub Pull Request installation.

As shown above,

Select the Extensions icon
Enter “GitHub” in the search box
And select the GitHub extension.
Selecting Install will install the extension
Clicking Repository will take you to the GitHub Pull Request Extension repository website, where more documentation can be found. Normally the documentation appears in the detail window below in Details.
Bring up the Sign In dialogue into the Command Bar, hitting Command Shift P, type GitHub Pull into the bar, and select Sign Into GitHub

This brings up a Browser Window. Note: I have Microsoft Edge as the default browser on my machine.

Copy the Token listed on the below screen print, and Click Continue.

This will bring up an authorization to open VSCode from the browser. You will notice an option with your token below, copy and save it just in case you need it for the following step. (Needed if you use two-factor or are a member of an organization)

You will see the following message;

Note that if this does not succeed, you can put the Authorization Token, Manually Provide Authentication Response setting. Click on the SIGN in to Github.com in the bottom right, the status bar.

Step 6 – 2 factor Authentication – Just in case

If you have an organization that has enabled two-factor authentication or have yourself, macOS needs a workaround that works for macOS in VSCode and the git command line. When you have the token from the step above, I prefer to set up an access token from the “developer settings” in the GitHub site and generate a “personal access token,” as illustrated below. You will be able to de-authorize this later by doing this set of steps. A further step will use this token in VSCode to authorize GitHub access.

You can use that token with your password when logging into VSCode, and that seems to work in most instances. Results may vary with your setup.

Log into Github.com, under your account, and select Settings.

2. After Selecting Settings, a tab for Developer Settings is at the bottom of the next page; select the logout.

3. On the Developer Settings menu, select Generate New Token.

4. The screen now displays and allows us to provide the access VSCode needs by using this token. Select the repo checkbox. Also, put in a name for this token, as you can edit or delete this token later in addition to having multiple tokens.

5. At the bottom of the list, you can then select Generate Token.

6. You will now see the token. Copy this token as you cannot view it once you leave the page.

Now that we have a token, let’s finish setting up our VSCode extension.

7. To use this token, we have to execute the ‘GitHub: Set Personal Access Token’ command in the VSCode Command Prompt. Type Ctrl+Shift+P in VSCode to open the command prompt window and type ‘GitHub: Set Personal Access Token.’ You will then be prompted to enter the token generated from GitHub.

8. Enter the token in the prompt, Hit Enter.

A Third Option If you are asked for a username and password, enter your GitHub user ID and put in the token you created on the GitHub site, developer settings, as the password. You should not be asked for this again.

There are some strange issues when using two-factor authentication and being a member of an organization. I was able to use the GitHub Developer settings method to get the authorization working.

SO,

You should now see your ID in the status bar.

Step 7 – Lets Open a Project to test this out

Now that we have VSCode connected, we can connect to a repository and begin. We will go to your GitHub account and create a repository.

Go to your GitHub repository listing.
Create a new repository using the New button.
Set up your details for the repository by filling in the screen, as shown in the below example. Select the Create repository button to continue.
Once you have the repository, get the clone link, by selecting the drop-down shown below.
This is the code that was supplied for my example.
https://github.com/steveyoungca/PythonTutorial.git
Open up GitHub Desktop, which will bring up the following screen. Select the Clone a repository from the Internet option.
This will bring up the following Clone a Repository screen. Select the URL tab and paste in the GIT Repository URL from step 4 . Notice the default directory created in the Local Path text box. Select the Clone button to begin.
This brings up the GitHub Desktop menu, which will show the repository. You also see the Open in Visual Studio Code option, as we set that as default in an earlier step. Select this option.
VSCode opens the project in the local directory. The files are displayed in the Explorer, and the GitHub status is the highlight on the bottom.
$C:\Users\styoung\AppData\Local\Temp\SNAGHTML3e7e9e7c.PNG$
Add a file or make a change to the Readme.md. Save the file, and you will notice the Source Control Pending Changes icon has a message with the number of files that have been modified and need to be checked in.

Click on the notification, which will bring up your list of changes. Add in a Message and hit Command Enter

Once you hit Command Enter with your message, your commit to your local machine repository is complete. You will see the message at the bottom of VSCode change to a 1 with an up arrow signifying you have a commit to push to the GitHub master branch for the project.

Now, Click on the 1 with the up arrow to push your changes to the repo.

You will now see the numbers disappear as your push was successful.

NOTE: It is important to note that the example we are running through is very simple. I use these tools in a single developer workflow and use this process to keep code versioning and the ability to save the project off the computer into GitHub.

If you work with a team of developers, you may check out and create your own branch. When you have finished your changes, you will merge your changes back into the Master branch.

Proper code hygiene and working with Git is beyond the scope of this article; however, using this process, you can certainly keep your own code in check if you will. A more detailed set of documentation is available on GIT in the article Distributed Git – Distributed workflows. This link is part of a full set of documentation on GIT.

Final Wrap up

Setting up VSCode integration with GitHub can be different if you have 2-factor authentication or are a member of another organization. I hope this helped !!!.

Thanks for reading 🙂 Steve