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 that you want to set up but is one of the most important. With the setup, having the ability to use Github as a code repository will definitely 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;
- Straight forward GitHub Authentication, User ID and PW
- 2 Factor which is in addition to option 1
- Are 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.
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 that this is not the first time installing an application. Some screens shots will be displayed, but any steps with simple choices are provided as written detail.
Step 1 – Install GIT onto macOS X
- From the main GIT Downloads website, select the latest version, 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 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 allow 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 on 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, just 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)
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 download.
- This, as the previous step, 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 could copy the app from the Download folder to the application folder, as shown below.
Configuration of 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.
|1||Menu Bar||Menu bar that also includes the Command Pallet which is activated by hitting CTRL-SHIFT-P.|
|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||Shows the changes that have yet to be checked-in to Source Control.|
|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 allows you to open up multiple tabs / code files in the same display.|
|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!!)|
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.
2 factor Authtication – 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 or my preference is to set up an access token from the "developer settings" in 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, select Settings.
- After Selecting Settings, at the bottom of the next page is a tab for Developer Settings, select this.
- On the Developer Settings menu, select Generate New Token.
- 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.
- At the bottom of the list, you can then select Generate Token.
- 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.
- 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.
- Enter the token in the prompt, Hit Enter.
A Third Option If you are asked for a user name 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 a member of an organization. I was able to use the GitHub Developer settings method to get the authorization working.
You should now see your ID in the status bar.
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.
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.
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 the list of changes you have made. 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 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 are 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