Enable Access to Your Source Code Repositories

The Xcode service operates on projects contained in source code repositories. The Xcode service supports two popular source control systems: Git and Subversion. You can use Git and Subversion repositories hosted on remote servers, and you can host and use Git repositories on the server running the Xcode service.

Connect to Remote Repositories

If you have projects in Git or Subversion repositories on remote servers, you can store your credentials for them in Accounts preferences in Xcode on your development Mac. Then you don’t have to reenter your credentials every time you need to access the repositories.

To add a remote repository’s credentials to a development Mac

  1. Choose Xcode > Preferences on your development Mac.

  2. Click Accounts.

  3. Click the Add button (+), and choose Add Repository.

  4. In the text field, enter the URL for the repository (for example, svn+ssh://svn.example.com/ProjectName or https://example.com/git/respository.git), and click the Next button.

  5. Choose either Git or Subversion from the Type pop-up menu.

  6. Enter your user name and password in the Repository pane of Accounts preferences, and click Add.

For the Xcode service to perform integrations on your projects, it must also have access to their repositories. Configure the Xcode service to connect to your remote repositories.

To add a remote repository to the Xcode service

  1. In the Server app sidebar, select the Xcode service.

  2. Click Repositories.

    ../art/RepositoriesTab_2x.png
  3. Click the Add button (+).

  4. Select either “Connect to a Git Repository” or “Connect to a Subversion Repository.”

  5. Enter a name for the repository.

    Use any name that helps you identify the repository. The name will appear in the Remote Repositories list in the Xcode service.

  6. Enter the URL for the repository (for example, svn+ssh://svn.example.com/ProjectName or https://example.com/git/respository.git).

  7. Select the type of authentication, and enter your authentication credentials.

    Click None if the repository requires no authentication. Click Password if the repository requires a user name and password. Enter them after selecting this method. Click SSH Key if the repository requires SSH key-based authentication and encryption. Enter the user name, and copy the public key to the server.

  8. Click Create.

    The name and address of the repository appear in the Remote Repositories list.

Host Git Repositories on the Server Running the Xcode Service

You can create and share Git repositories on the computer with OS X Server installed. Git is a free, open-source version management system for code. (For more information about Git, see the project web site.) If you work on a team of developers, they can share and manage their code changes in these repositories.

Configure the Xcode service to allow users to create and gain access to hosted source code repositories.

To configure repository access in the Xcode service

  1. In the Server app sidebar, select the Xcode service.

  2. Click Repositories.

  3. Make sure the checkbox for “Allow access to hosted repositories” is selected. Click the associated Edit button to select which protocols can be used to access the hosted repositories.

    By default, the HTTP and HTTPS protocols are selected.

    You can also select SSH. If you select SSH, the Xcode service displays a dialog asking whether to allow remote login using SSH. Click Allow.

    HTTP and HTTPS offer the most flexibility, because these protocols work in most network environments. Your authentication credentials are encrypted with HTTP, but the remainder of your transactions—consisting mainly of your source code—aren’t encrypted. With HTTPS, your transactions are encrypted along with your credentials, but you need a valid certificate signed by a public certificate authority.

    SSH encrypts credentials and transactions. However, SSH isn’t as readily available as HTTP and HTTPS across network environments.

    SSH is a good, secure choice and is useful if your organization uses SSH keys for authentication. HTTPS is a good, secure choice if you have SSL certificates for the server. HTTP is a good choice if you don’t have SSL certificates, and aren’t planning on accessing code outside your local network or over an encrypted connection. For more information about these protocols, see OS X Server: Advanced Administration.

  4. Click the lower Edit button to select the users who can create hosted repositories.

  5. In Accounts preferences in Xcode on your development Mac, add your account credentials for the server (if you haven’t already done so).

If you work with a team of developers, you can give them accounts for accessing repositories on the server (as described in “Set Up the Xcode Service for Team Members”).

Clone a Local Repository from Your Development Mac to the Server

If you use a Git repository local to your development Mac, clone the repository to the server running the Xcode service, thereby allowing the Xcode service to operate on the repository.

To clone a local repository to a server running the Xcode service

  1. Open the project on your development Mac, and choose Source Control > ProjectName > Configure ProjectName.

  2. Click Remotes.

  3. Click the Add button (+).

  4. Choose Create New Remote.

  5. Select the server.

  6. Enter a name for the remote repository.

    Use any name that helps you identify the repository. The name will appear in the Remotes list on your development Mac when you need to select this repository. For example, when you choose Source Control > Push and Source Control > Commit, the name appears in a pop-up menu that allows you to specify the remote repository.

  7. Click Create.

    The cloned repository appears in the Hosted Repositories list in the Xcode service.

  8. Click Done.

    Your local repository is copied to the server.

If you work with a team of developers, you can give them accounts on the server to share your repository, as described in “Set Up the Xcode Service for Team Members.”

Create a Project and Host its Repository on the Server

When you create a project on your development Mac, you can simultaneously create a repository for it on the server.

To create a project with a Git repository on a server running the Xcode service

  1. In the Accounts preferences in Xcode on your development Mac, add your account credentials for the server (if you haven’t already done so).

    By default, the Xcode service allows hosted repositories to be created by logged in users. Adding your account credentials for the server in your Accounts preferences in Xcode allows you to log in automatically when creating a Git repository on the server.

  2. Choose File > New > Project.

  3. Choose a template for your project, and click Next.

  4. Specify options for the project, and click Next.

  5. Specify the location for the local working copy of the project.

  6. For the Source Control option, select “Create git repository on.”

  7. Use the associated pop-up menu to choose the server on which to host the repository.

    ../art/ChooseRemoteGit_2x.png

    If the server doesn’t appear in the list, look—or ask the server administrator to look—in the Repositories pane of the Xcode service to see whether you have permission to create a repository. Depending on how the Xcode service is configured, hosted repositories can be created by logged in users, anyone, or only specified users.

  8. Click Create.

On the server, the name of the project appears in the Hosted Repositories list of the Xcode service. If you work with a team of developers, you can give them accounts to share your repository (as described in “Set Up the Xcode Service for Team Members”).

Create Git Repositories on the Server and Access Them from Your Development Mac

You can create sharable Git repositories on the server running the Xcode service.

To host a new Git repository on a server running the Xcode service

  1. In the Server app sidebar, select the Xcode service.

  2. Click Repositories.

  3. Click the Add button (+).

  4. Choose “Host a Git Repository.”

  5. Enter a name for the repository.

    Use any name that helps you identify the repository. This name will appear in the Hosted Repositories list in the Xcode service and will be part of the access URL.

  6. Identify the users allowed to access the repository.

    Select “All authenticated users” to give access to all users who can log in to the local server or the directory.

    Select “Only some users" to set up an access list for users on the local server or in the directory. You can choose who can read or who can read and write to the repository.

  7. Click Create.

    The new repository appears in the Hosted Repositories list. If you want to change user access permissions later, select the repository from the Hosted Repositories list and click the Edit button.

    You can add your credentials for this repository to your development Mac by using Accounts preferences in Xcode on that Mac. If you work with a team of developers, you can give them accounts on the server to share the repository, as described in “Set Up the Xcode Service for Team Members.”

If you have an existing Git repository on your local development Mac, you can clone it to the new repository on the server.

To add a Git repository hosted by the Xcode service to a project on a development Mac

  1. Open the project on your development Mac, and choose Source Control > ProjectName > Configure ProjectName.

  2. Click Remotes.

  3. Click the Add button (+).

  4. Choose Add Remote.

  5. Select the server.

  6. Enter the name and address for the remote repository.

  7. Click Add Remote.

  8. Click Done.

Push Your Commits to the Hosted Repository on the Server

After you configure your development Mac to use a Git repository on the server, a commit operation adds your changes to your local repository. As with any remote Git repository, you must also perform a push operation to add your committed changes to the repository on the server. For example, when you choose Source Control > Commit on your development Mac, select the “Push to remote” option, specify the remote repository in the pop-up menu, and click Commit Files.

Use Git to Manage an Unmanaged Workspace Directory on a Development Mac

When you create an Xcode workspace or project, you have the option of including a Git repository in the generated workspace directory. If you didn’t select that option, your workspace directory doesn’t include a Git repository. To share a workspace directory with others using the Git version control system, you must initialize a Git repository in that directory.

To initialize a Git repository in a workspace directory

  1. In the Terminal app, run the git init command inside the workspace directory:

    cd <workspace_directory_path>
    git init
  2. Identify the files you want to track in the repository with the git add command:

    git add <files>
  3. Add the files to the repository with the git commit command:

    git commit -m "<workspace_directory> initial commit"

For example, these commands initialize a Git repository inside the Sketch workspace directory, identify the files in the directory to be tracked (excluding some), and add the files to the newly created repository:

hedy: Desktop $ cd Sketch
hedy: Sketch $ git init
Initialized empty Git repository in /Users/ernest/Desktop/Sketch/.git/
hedy: Sketch $ cat > .gitignore
.DS_Store
xcuserdata
^D                         # Control-D
hedy: Sketch $ git add .
hedy: Sketch $ git commit -m "Sketch initial commit"
[master (root-commit) db941e7] Sketch initial commit
 73 files changed, 13157 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Arrow.tiff
 create mode 100644 Circle.tiff
...

To allow the Xcode service to operate on the repository, clone the repository to your server, as described in “Clone a Local Repository from Your Development Mac to the Server.”