Developer Diaries: using remote repositories with Xcode 5 bots
> If you just need to know how to quickly setup your remote repository to use with bots with Mac OS X Server Xcode process and Xcode 5, you may jump directly to Section How to setup your external repository. If you want to know why, keep reading.
Git with ssh follows the standard ssh URI format:
Following the RFC3986, a non-empty path must begin with the slash '/' character (see Section 3.3 of the RFC3986 document).
When used with the ssh transport protocol, git also allows for the scp-like syntax, which uses a colon ':' to separate the authority component from the path component of the URI. Using the shorter scp-like syntax, the above URI could be specified as follows:
or, assuming that /home/username is a home directory of a user named username, we could write:
Notice that in the scp-like syntax you don't keep the scheme name at the beginning of the URI (no ssh:// in the example above). Git will use the ssh transport protocol by default.
Standard URIs also provide a way to shorten the path when referring to the user's home directory. The tilde '~' unreserved character (see Section 2.3 of the RFC3986 standard) can be used for this purpose. The actual meaning of this character is not standardised, but I can't recall ever seeing this character interpreted differently by any URI parser.
Using the tilde '~' character, we can shorten our full ssh URI as follows:
The scp-like syntax also supports the tilde '~' character with exactly same meaning. The two URIs below are therefore equivalent:
In each case you can skip the .git extension and achieve the same effect:
The problem with the scp-like syntax for URIs is that it is not really standardised and as such does not have to be supported everywhere - it turns out that at the time of this writing Apple's Xcode 5 is one such place.
> What I am describing here is my experience. Your experience may be different depending on the version of the tool you are using. Apple may also change the they implement their git client in the nearest future. What I describe may therefore be quite specific, still I believe it may point you to the right direction.
I have an iOS project. The project is under version control. It uses git. It only has one remote:
As you see, in the remote's URI I am using the scp-like syntax.
I open the project with Xcode 5 and it recognises that the project is under version control. It also seems to recognise my repository remotes without any issues (this dialog window can be accessed in Xcode 5 via Source Control/my_cool_project - master/Configure... menu):
You can see on the picture that the repository Origin is:
However, if you look into the Remotes tab of the same dialog, you will find something slightly different:
What we see in the picture is:
Well, it looks like Xcode decided to convert the scp-like syntax into a more standard ssh format, but did not realise that my scp-like URI points to the home folder of user steve. The closest ssh URI for the above scp-like URI would be:
It seems that Xcode 5 blindly replaces the colon ':' character from the scp-like syntax with the slash '/' character in the ssh URI. Therefore, in order to get a correct URI after Xcode's manipulation we should use the following scp-like URI as the input:
Xcode 5 will translate this URI into the following one:
> If you want to replicate this, use a real repository. Surprisingly enough, Xcode 5 does not bother to touch your URI if it is fake or when it does not align with what Xcode may find in the .git folder.
It matters because your Mac OS X Server Xcode service may end up using an incorrect URI for the repository. In our example, if the remote URI is set to:
your bot will not be able to connect to the remote repository:
If you configure the remote URI as described in the next section, you will be able to connect to the remote repository:
How to setup your external repository
On your Mac OS X Server in the Xcode service add a new remote repository. Make sure that your repository uses format that is correct, i.e. if you use an scp-like syntax for the repository URI, make sure that you use the tilde '~' character after the colon if your intention is to point to the user's home directory.
Of course you can always use a valid ssh URI directly:
or even an absolute path:
On your development machine, in Xcode, make sure that your remote is the same as the one you used on the server. You can view and change your remote settings through the Source Control/my_cool_project - master/Configure... menu.
Create a new bot. If your remote updated in the previous step does not match any remote repository URI on the Mac OS X Server, you will be asked for your repository credentials:
As you see, this is not very useful, as this dialog does not let you use the public key authentication. Cancel, align your remote with your server, and try again. If everything is correct, you won't be asked to provide any further details about your remote.
Xcode 5 shows the bots that are relevant to the project in the log navigator:
How does Xcode know which bots are relevant? Xcode looks at your repository remote URI. If it finds a bot associated with your remote URI, it will display the bot in the log. You can change the remote URI in Xcode and you will see that your bot disappears from the log navigator. In a similar way, when you change the URI of the remote repository on the server, the bot in Xcode will disappear as soon as you restart Xcode.
> Hint: if your bot is not visible after changing the URI on the server, try restarting Xcode 5 (do not only reopen the project: restart the whole IDE).
When changing URI of the remote repository on the server you may need to update your private key as well. It seems that the server wipes the private key each time you change the repository URI treating it as a new repository.
