Linking Android Studio and GitHub

An FTC team that uses Android Studio for robot programming should also use cloud storage for backup, and to facilitate file sharing. GitHub is the most popular (but not the only) choice.

Android Studio and GitHub play well together! There are features provided in Android Studio that make GitHub integration easy. But you have to establish authentication credentials to connect an Android Studio project to a GitHub account, and remote repository. Until recently, you could use the familiar Account Name and Account Password pair to authenticate. But that’s no longer possible. To improve security, GitHub now requires a different method for computer applications to authenticate to their accounts. The easy-to-remember Name and Password is a thing of the past. (This change took effect on August 13, 2021. Some returning FTC programmers are in for a surprise.)

Individual developers and programmers usually manage their authentication needs with a Git Credentials Manager add-on program. This may not work well for an FTC team, where several programmers may be using classroom computers, from a pool shared between teams, or their own personally-owned computers - or both. Many teams are part of a larger sponsoring organization, such as a school; there are some advantages to using a workflow and process common to all teams sponsored by the same organization.

We at the Princeton STEM Academy would like to share the authentication workflow we use with the FTC community. We hesitate to call it a “best practice” - but it works for us, and it may work for your teams.

Pros:

• Works for a pool of shared classroom computers
• Works for computers that may be shared between several teams
• Works for team members’ personally owned computers
• Management and administration is nearly identical for Windows, Macs, and Linux systems
• Setup on multiple computers can be automated through scripts
• Does not require installation of a credential manager (helper application)
• Supports removing access from a personally owned computer when a student leaves the team

Cons:

• Not secure: credentials are stored without encryption on each computer
• Requires some familiarity with Command Line functions

The Personal Access Token (PAT): Keys to the Kingdom

We use GitHub-generated Personal Access Tokens (PATs) to identify an Android Studio request to GitHub as authentic. The PAT is a 40 character sequence of mostly random-appearing text, e.g.:

ghp_PersonalAccessTokenForAnArbitraryxyz

(The first four characters are always “ghp_”.) Your teams’ GitHub accounts will still have Account Names and Account Passwords, but they will no longer work for Android Studio operations.

How many PATs do you need?

You will need at least one PAT for each GitHub account. At The Princeton STEM Academy, we have several shared computers for programming, and like to keep them as interchangeable as possible, from the FTC programmers’ viewpoint. With three teams, each computer has the same three PATs for the individual team repositories. They all get installed the same way, from a script (Windows Command Prompt .BAT file).

For individual team members’ personally owned computers, we generate individual PATs, tied to that team member’s identity. This way, when a team member departs, we can delete only their own PAT, affecting nobody else. The recordkeeping burden is not large.

In summary, for each team’s GitHub account, there will be individual PATs for each of the programmers, plus one for all of the Academy computers to share.

Creating a PAT

You can create as many PATs as you need from the GitHub page for your team’s account. Log in to the account, and open the menu from the profile icon at the top right (1). Select “Settings” (2). From the menu on the left, near the bottom, select “Developer settings” (3).

On the GitHub Apps page, select “Personal access tokens”. This next page will list all of the PATs for the account, by the name or comment entered when each was created. You can delete tokens at will from here - for example, if a programmer has left the team, his / her token should be deleted. You can also edit access rights by clicking on the name / comment. For now, click on “Generate new token”.

On the “New personal access token” page, enter a descriptive note for this PAT (4). For example, a team programmer’s first name, last initial, and team number. Select an expiration date, or “No expiration” (5). For “Select scopes”, click “repo” (6), which will populate the entire repository block. (That’s probably all of the scope a typical FTC programmer will ever need.)

A note on expiration dates: GitHub presents you with options, such as 7, 30, 60, or 90 days, a custom “date certain”, and “No expiration”. GitHub will display a security warning if you select “No expiration”. We don’t think that “No expiration” presents much of a problem at the PSA: Our team enrollment changes little from year to year, and remains active during the summer. We just manually delete or regenerate PATs when students leave a team, or replace their laptops. For a school-based team that shuts down at the end of the academic year, it might be preferrable to set PATs for students’ personally-owned laptops to expire in June. Set your own policy, keeping in mind that you will only need a small number of PATs.

Scroll down, and click the green “Create token” button when you are done.

Immediately copy the generated PAT, and paste it somewhere safe. You will not be able to recover the PAT from within GitHub after you navigate away from this page. Save your collection of PATs, along with any notes you may want to keep, somewhere appropriate for the level of security you need.

(In case you were wondering, I deleted this particular demonstration PAT as soon as I took the screenshot.)

Credential Formats, and Using the PAT

A simple GitHub remote repository credential is just the complete URL. For team Xenon, with a GitHub account xenon-ftc, their Ultimate Goal repository URL might be:

https://github.com/xenon-ftc/Ultimate-Goal.git

You insert the PAT into the URL immediately after https://, separating it from the host name (github.com) with an @ sign. For team Xenon, the credential with authentication token might be:

https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon-ftc/Ultimate-Goal.git

Note the “at” sign (“@”) between the PAT, and the rest of the URL. (For the record: if Account Name / Password authentication were still accepted, the format would have a colon separating the Account Name and the Password:)

https://AccountName:Password@github.com/xenon-ftc/Ultimate-Goal.git

Cloning with a PAT

The easiest way to incorporate the PAT into a local Android Studio project is to do it while cloning the remote repository. Open a Command Prompt in your project’s parent directory of choice. Instead of:

git clone https://github.com/xenon-ftc/Ultimate-Goal.git

Do this:

git clone https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon-ftc/Ultimate-Goal.git

From inside the newly-created project folder, you can confirm that the PAT is now part of the project with git remote -v, which will show something like:

origin  https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon-ftc/Ultimate-Goal.git (fetch)
origin  https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon-ftc/Ultimate-Goal.git (push)

That’s all there is to it. You can start Android Studio, open the Ultimate-Goal project, and Android Studio will be able to Update and Push code to GitHub without further Account Name or Password prompts. All of the authentication is in the PAT.

Scripting

If you’re supporting a pool of shared programmers’ computers, automating your installations will be a real labor-saver. For example, suppose you want to clone the Ultimate Goal and Skystone repositories for three sister teams, xenon, radon, and argon, on a bunch of new laptops. Your script (a Windows Command Prompt .BAT file) might look like this:

C:
cd android-workspace
mkdir xenon
mkdir radon
mkdir argon

cd xenon
git clone https://ghp_SharedTeamabcdTokenForTeamXenonefgyz@github.com/xenon-ftc/Ultimate-Goal.git
git clone https://ghp_SharedTeamabcdTokenForTeamXenonefgyz@github.com/xenon-ftc/Skystone.git
cd ..
cd radon
git clone https://ghp_SharedTeamabcdTokenForTeamRadonefgyz@github.com/radon-ftc/Ultimate-Goal.git
git clone https://ghp_SharedTeamabcdTokenForTeamRadonefgyz@github.com/radon-ftc/Skystone.git
cd ..
cd argon
git clone https://ghp_SharedTeamabcdTokenForTeamArgonefgyz@github.com/argon-ftc/Ultimate-Goal.git
git clone https://ghp_SharedTeamabcdTokenForTeamArgonefgyz@github.com/argon-ftc/Skystone.git
cd ..

Load it on a flash drive, start it on each new laptop, and drink coffee while it runs.

Working with an Existing Project

If you already have an Android Studio project installed on a computer and want to add a PAT to the credentials: The sure-fire way to make it work is to delete the old project folder, and clone a new project folder, using the procedure above.

Precaution: Please make sure that Android Studio does not have the project open when you delete and re-clone. Use File | Close Project in Android studio to avoid conflicts.

You may find a situation where deleting the old content on the computer would result in loss of work, perhaps because somebody forgot to “Push” their work at the end of last season. You can update the remote references to save that work, but it requires a little more Git command line skill (example):

git remote rename origin origin_old
git remote add origin https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon-ftc/Ultimate-Goal.git
git remote remove origin_old
git push

The last command will fail because there’s no recorded upstream branch for the new remote repository. The error message will contain the text of the command you should run to fix that: copy it out of the message, and paste it back at the prompt to run it.

Or, at your own risk, you could edit the configuration file directly. From a Command Prompt in your project folder, cd .git (that’s “dot git”, not “git”) to find the git local configuration file, config. Make a backup copy! Open it with a plain text editor, like Notepad:

notepad config

Contents will be something like this:

[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
[remote "origin"]
        url = https://github.com/xenon-ftc/Ultimate-Goal.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
        remote = origin
        merge = refs/heads/main
[branch "GlobalClass61"]
        remote = origin
        merge = refs/heads/GlobalClass61

Find the url line, and paste in your PAT:

[core]
        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
[remote "origin"]
        url = https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon-ftc/Ultimate-Goal.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
        remote = origin
        merge = refs/heads/main
[branch "GlobalClass61"]
        remote = origin
        merge = refs/heads/GlobalClass61

This is obviously a bit of a risk: these files are not meant to be edited by a human. But it should work, and may save you the trouble of fixing the upstream branch records if you have lots of branches.

Step-by-Step Examples

In practice, this is really pretty easy. I’ll provide two sample “Use Cases”, from my own practices at the PSA:

Use Case 1: Initializing a PowerPlay Team Repository

Scenario: A Coach (or veteran team programmer) for team Xenon needs to create a new PowerPlay repository for the season, initialize it with FTC SDK 8.0, and add the repository to the existing team GitHub account. She is using the same computer she used during the FreightFrenzy season, which still has that repository, and a valid Personal Access Token (PAT).

This process is only done once, to create the new team repository. For additional computers and programmers, use the procedure below to clone from the team GitHub account.

For this example, assume that team Xenon has a folder beneath the android-workspace folder. I’m using Windows terminology, here. Mac (or Linux) procedures will be nearly identical.

Log in to the team GitHub account, and create a new repository with the name PowerPlay. (Steps not shown.)

Open a Command Prompt window. Change directory into team Xenon’s repository folder:

cd android-workspace\xenon

Clone a new repository from the FIRST-Tech-Challenge/FtcRobotController repository. Note that we’re changing the name to PowerPlay on the local computer:

git clone https://github.com/FIRST-Tech-Challenge/FtcRobotController.git PowerPlay

Change directory into the previous season (FreightFrenzy) repository folder, and display the remote repository (i.e., GitHub) connection:

cd FreightFrenzy
git remote -v

This will display the GitHub repository URL, including the vaild PAT, looking something like this:

origin  https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/FreightFrenzy.git (fetch)
origin  https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/FreightFrenzy.git (push)

Highlight (with your mouse) the URL from either line, from http: to, but not including, the repository name, right-click and “Copy” the selected text to your clipboard. This is the part you want:

https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/

Next, change directory out of the FreightFrenzy repository, and into the new PowerPlay repository:

cd ..
cd PowerPlay

Remove the remote repository connection to the FIRST-Tech-Challenge account:

git remote remove origin

And start composing a new connection by typing git remote add origin, typing a space, and “Pasting” in the contents of the clipboard. It should look like this:

git remote add origin https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/

Next, on the same line, type PowerPlay.git:

git remote add origin https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/PowerPlay.git

And hit “Enter”. No messages mean that there were no errors; that’s what we want. (The above hand-crafted command creates a new remote repository (GitHub) connection, with the PAT copied from FreightFrenzy, but otherwise pointing to the new PowerPlay repository.)

Finally, enter:

git push -u origin main

which will set up the default branch, and push the contents of the local repository to the team GitHub account.

Use Case 2: Cloning an Existing PowerPlay Repository for a Returning Team Programmer

Scenario: A returning programmer for team Xenon needs to clone the PowerPlay repository from the team GitHub account (see above) to his personally-owned laptop. It’s the same laptop he used last year, and still has a good repository for FreightFrenzy, with a valid Personal Access Token (PAT).

This is easier than the previous Use Case, as the GitHub repository already exists. The programmer does not have to log in to GitHub at all: Everything gets done with the existing PAT.

Open a Command Prompt window. Change directory into the programmer’s repository home folder (which probably won’t include the team name as part of the path):

cd android-workspace

Change directory into the previous season (FreightFrenzy) repository folder, and display the remote repository (i.e., GitHub) connection:

cd FreightFrenzy
git remote -v

This will display the GitHub repository URL, including the vaild PAT, looking something like this:

origin  https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/FreightFrenzy.git (fetch)
origin  https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/FreightFrenzy.git (push)

Highlight (with your mouse) the URL from either line, from http: to, but not including, the repository name, right-click and “Copy” the selected text to your clipboard. This is the part you want:

https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/

Next, change directory out of the FreightFrenzy repository:

cd ..

And start construcing the “clone” command, by typing git clone, followed by a space, and “Paste” in the URL copied from the old repository, so it looks like this:

git clone https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/

Next, add, on the same line, the name of the new GitHub repository:

git clone https://ghp_PersonalAccessTokenForAnArbitraryxyz@github.com/xenon/PowerPlay.git

And hit “Enter”.

That’s it; you’ll see some messages as the repository is cloned from GitHub to the local computer. You’re good to go!

Use Case 3: Cloning an Existing PowerPlay Repository for a Returning Team Programmer

Scenario: You’re setting up shared (classroom) computers with repositories for one or more teams.

For one team, you can use the same procedure as for a team member’s personally-owned laptop. For several teams, I recommend having subdirectories underneath the Android Studio workspace default location. This will let you keep the same repository name across all of your teams, which may simplify management.

.\android-workspace\xenon\PowerPlay
.\android-workspace\radon\PowerPlay
.\android-workspace\argon\PowerPlay

There’s one more useful step. When pusing a commit from Android Studio to GitHub, the push includes a record of the user name and user email doing the push.

With shared (classroom) computers, there’s no easy way to individualize that information. However, you can make each team repository have entries that are team-specific.

A script might look something like this:

cd xenon\PowerPlay
git config --local user.name="Xenon"
git config --local user.email="xenon@gmail.com"
cd ..\..
cd radon\PowerPlay
git config --local user.name="Radon"
git config --local user.email="radon@gmail.com"
cd ..\..
cd argon\PowerPlay
git config --local user.name="Argon"
git config --local user.email="argon@gmail.com"
cd ..\..

You should set some default value for user.name and user.email. Leaving them undefined will cause Android Studio to present a confusing pop-up when pushing commits to GitHub, otherwise.