Ever wished you could use a source control system with your Codea projects? Interface with your repositories at GitHub, Bitbucket, GitLab, or your very own server in the cloud? Now you can, with a little help from Codea-SCM.
The basic idea is simple: instead of you doing the source control commands locally - such as git clone, git commit, git push, and so for - the Codea-SCM web service does them on your behalf. To authenticate each action, the web service uses SSH protocol to connect to remote repositories, and the authorizaton is left to the repository hosting service (such as GitHub or Bitbucket) - that is, to check whether you are authorized to do a particular action (push, clone, etc.) Since SSH keys are used for authentication, you never need to give your GitHub or Bitbucket account password (or username) to the Codea-SCM web service.
For more detail on security aspects, see this section below: Security Q/A
Step 1. Create a new project, call it something reasonable, for example, codea-scm.
Step 2. Paste this code into Main tab, replacing the default content:
--# Main
-- codea-scm bootstrap installer
function setup()
displayMode(STANDARD)
print("Installing codea-scm ...")
http.request("https://codea-scm.aws.mapote.com/install",
function (data, status, headers)
assert(loadstring(data))()
print("Installation complete. SUCCESS!")
print("Launch the project again to start using codea-scm.")
tween.delay(2.0, close)
end,
function (err)
print("PROBLEM downloading: " .. err)
end)
end
function draw()
background(37, 38, 50, 255)
end
Step 3. Run it - it will download the rest of the Codea-SCM code and exit. Then start the project again to launch Codea-SCM.
(Remember that you can always examine what is being downloaded and executed by the installer: just follow this link: https://codea-scm.aws.mapote.com/install)
TopThe assumption here is that you are somewhat familiar with the concepts of distributed source control systems - such as git, for example, and also have a basic understanding of how public-key cryptography is used for authentication purposes.
First thing you need to do is create an identity for yourself and log in. Click Login button to start that process. The identity in this case consists of 2 things: a username, and an SSH keypair. You can pretty much pick any username you want, consisting of letters and digits. The username will be used as a name of your keypair, and (like the keypair), is only stored locally on your device and nowhere else (it is stored in the project's local data - via saveLocalData function). Once you've chosen a username and clicked login button, the app will check the project's local data to see if you already had created a keypair associated with this username. If not, it will show the New keypair button - this allows you to use the Codea-SCM server to create a keypair and deliver it securely onto your device.
Now that you are logged in, it is time to add projects for codea-scm app to track. To add a project, you must enter project's name (with proper capitalization - exactly as it is named in Codea), and a remote. Make sure to use SSH protocol for remotes, not HTTPS. For example:
To find out your public key: make sure you are logged in, then click on User (somename) button, which will show you the user menu. Then click on Show public key button to open an in-app browser, which will echo your public key back to you. This way you can select it and copy.
In order for SSH authentication to work, a repository hosting site that you use as a remote (for example, Github, Bitbucket, etc.) needs to be made aware of your public key. Many hosting sites (seems like all the popular ones, at least) support using SSH keys for authentication. They all have slightly different web interfaces for adding a public key, but the workflow is typically the same: go to a page that manages settings for your account, there will be a section called "SSH keys", then choose an option to "Add key", and paste your public key in there.
You are ready to use the program, finally :) There are basically 3 operations that you can perform:
Touch the button with project name on it. This will perform a diff of your current code on the device against the latest version stored in the remote repository. If there is no difference, the status circle will turn green. If there are changes, then it will become blue, and the diff will be shown in a scrollable overlay window.
The grey circle means that status cannot be determined. Typically, that would be due to no access to the remote repository, whether because your key is not authorized for access, or because of some error: an incorrectly specified remote or project name, for example.
Touch the push button next to a project. This will upload your current code to Codea-SCM server (POST over https), do a commit (with the comment provided), then push the commit to the remote repository. We assume here that you have already created remote repository on a hosting site, such as Github, for example.
Touch the pull button next to a project. This will let you pull a version of your code from the remote repository - you can either specify any version manually, or pick from recent history. (If you pull any version other than the latest, the status circle will turn purple).
Q: Communication between the device and Codea-SCM web service - is it secure?
A: Yes. Codea-SCM web service provides its API endpoints only via HTTPS protocol. So the communication channel between your iPad and the web service is always secure.
Q: Is Codea-SCM web service vulnerable to OpenSSL Heartbleed bug?
A: No. The server has been updated to the patched version of OpenSSL, which addresses the vulnerability. See SSL-Labs test results.
Q: Communication between Codea-SCM web service and repository hosting site (GitHub, for example) - is it secure?
A: Yes. Remote repositories are always accessed via SSH connection, so that communication link is also secure.
Q: Does Codea-SCM server store any sensitive data (keys, passwords)?
A: No. Codea-SCM server does not keep any user-related data or credentials. The SSH keypairs that it generates for users are never stored on disk, and because of that, a keypair is only available for download once - in the response to the request that generated it. Private keys sent via API requests only briefly exist in memory, long enough to establish SSH connections to the remote repositories.