Enable Access to Your Source Code Repositories

Xcode Server operates on projects contained in source code repositories, and 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 Mac computer that’s running Xcode Server.

Connect to Remote Repositories

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

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

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

  1. Choose Xcode > Preferences on your development Mac.

  2. Click Accounts in the toolbar.

  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/repository.git), and click the Next button.

  5. Enter your user name and password in the Repository pane of Accounts preferences.

Host Git Repositories with Xcode Server

You can create and share Git repositories with Xcode Server. If you work on a team of developers, they can also 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 Xcode Server

  1. In the Services list in the Server app sidebar, select Xcode.

  2. Click the Repositories tab, and you’ll see something like this pane:

    ../art/server_repository_tab_2x.png../art/server_repository_tab_2x.png

     

  3. Under Access, click the Edit button to configure which protocols can be used to access the hosted repositories.

    ../art/server_repository_access_2x.png

    By default, HTTPS is 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.

    HTTPS offers the most flexibility because this protocols works in most network environments. With HTTPS, your authentication credentials and transactions are encrypted, and you need a valid certificate signed by a public certificate authority.

    SSH encrypts credentials and transactions. However, SSH isn’t as readily available as 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. For more information about these protocols, see OS X Server: Advanced Administration.

  4. Click the Edit button in the Access area of the Repositories tab to select the users who can create hosted repositories.

    ../art/server_repository_permissions_2x.png
  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 allow HTTPS access, anyone using HTTPS to access a hosted repository is presented with a certificate dialog in Xcode. To access the repository from your development Mac, click Show Certificate when the certificate dialog appears, select the Always Trust option, and click Continue.

../art/website_certificate_notice_2x.png

If you work with a team of developers, you can give them accounts for accessing repositories on the server (as described in Set Up Xcode Server 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 Xcode Server to operate on the repository.

To clone a local repository to a server running Xcode Server

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

    ../art/xcode_configure_repository_2x.png
  2. Click Remotes.

  3. Click the Add button (+).

  4. Choose Create New Remote.

    ../art/xcode_create_remote_repository_2x.png

     

  5. Select an OS X server that is running Xcode Server.

  6. Enter a name for the remote repository.

    ../art/xcode_create_remote_repository2_2x.png

    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 either Push or Commit from the Source Control menu, 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 Repositories list in Xcode Server on your OS X Server.

    ../art/server_remote_repository_2x.png../art/server_remote_repository_2x.png

     

  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 Xcode Server 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 pop-up menu to select the server on which to host the repository.

    ../art/ChooseRemoteGit_2x.png../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 Xcode Server to see whether you have permission to create a repository. Depending on how Xcode Server is configured, hosted repositories can be created by logged in users, anyone, or only specified users.

  8. Click Create.

On the OS X server, the name of the project appears in the Hosted Repositories list of Xcode Server. If you work with a team of developers, you can give them accounts to share your repository (as described in Set Up Xcode Server 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 Xcode Server.

To host a new Git repository on a server running Xcode Server

  1. In the Services list in the Server app sidebar, select Xcode.

  2. Click Repositories.

  3. Click the Add button (+).

  4. Enter a name for the repository.

    ../art/server_create_repository_2x.png../art/server_create_repository_2x.png

     

    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.

  5. Click the Edit button to identify the users allowed to access the repository via SSH.

    Select “logged in 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.

  6. If you want to enable HTTPS access, select the “Allow logged in users to read and write” checkbox.

  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 Xcode Server 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 Xcode Server to a project on a development Mac

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

  2. Click Remotes.

  3. Click the Add button (+).

  4. Choose Add Remote.

    ../art/xcode_add_remote_2x.png

     

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

    ../art/xcode_add_remote2_2x.png

    You can find the address for the remote repository in the list of repositories in Xcode Server.

  6. Click Add Remote.

  7. 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 and Push.

../art/xcode_commit_push_to_remote_2x.png

Add Git Support to an Existing Project

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 won’t include a Git repository and you won’t be able to use your project with Xcode Server. To share a workspace directory with others using the Git version control system, you must manually initialize a Git repository in that directory.

To manually 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, the following 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.