Howto: Install Jenkins on OS X and make it build Mac stuff

This guide is intended for Lion users. I just tried it on my machine, and it works. Let’s hope it works for you as well.

What’s covered:

  • How to install Jenkins as a standalone Service
  • How to configure a Job that builds a generic Mac-Application
  • Configuring Public Key SSH-Access ( Useful for git )
  • Java must be installed
  • XCode ( any version that works on Lion will do )
  • You shouldn’t have any services running on port 8080

Installing Jenkins

Jenkins is available as a native package from the Jenkins homepage.  Just install it, as you would install any other package. After you’ve done that, you might want to check if http://localhost:8080/ is reachable. If it’s not, you may have to launch the .war-File by opening it. It’s located in /Applications/Jenkins/.

In case the server is running, you’ll most likely get a 404 ‘not found’ message from the winstone-server that is bundled. If you dig in your syslog, you’ll find a reviling stack trace that indicates that a file can’t be found.. /Users/Shared/Jenkins/Home/war/META-INF/MANIFEST.MF (No such file or directory)

I don’t know why the package is broken, but it’s quite easy to fix this. I found some great advice on

First, we’ll create a dedicated jenkins user. At this point, there isn’t one, so just type this into your terminal

sudo dscl . create /Users/jenkins
sudo dscl . create /Users/jenkins PrimaryGroupID 1
sudo dscl . create /Users/jenkins UniqueID 300
sudo dscl . create /Users/jenkins UserShell /bin/bash
sudo dscl . create /Users/jenkins home /Users/Shared/Jenkins/Home/
sudo dscl . create /Users/jenkins NFSHomeDirectory /Users/Shared/Jenkins/Home/
sudo dscl . passwd /Users/jenkins

Now that you have created the user, it’s time to tell the LaunchAgent that came with the install package to use this user to run Jenkins. The file you have to change for this is located at /Library/LaunchDaemons/org.jenkins-ci.plist . Just open it in your favorite editor and change the value of UserName to jenkins.


After doing that, the Home folder of jenkins, /Users/Shared/Jenkins/Home needs a new owner.

sudo chown -R jenkins /Users/Shared/Jenkins

After doing all that, saving the modified launch file and chown’ing the Home, unload and reload the service:

sudo launchctl unload -w /Library/LaunchDaemons/org.jenkins-ci.plist
sudo launchctl load -w /Library/LaunchDaemons/org.jenkins-ci.plist

Now you should be greeted by Jenkins if you try again localhost:8080. If not make sure that you followed the steps above correctly. If you did that but it still doesn’t work, please leave a comment.

If you need to access your git repos using a public ssh key, you can generate one now by logging in as the jenkins user and running ssh-keygen

# su jenkins
bash-3.2$ ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key...

You can then upload the file to wherever you need it.

 Create a Job for a XCode Project

Before we dive right in, you need to install the git-plugin. This is done by navigating to “Manage Jenkins” from the welcome screen and then selecting plugins. There are about a million, but you just need git for the moment, as I assume that your project is using git. Once you’ve installed the plugin, set up your git username and email in the “Manage Jerkins” “Configure System” menu. If you omit that step, the source retrieval will fail.

Having setup Jenkins now, it’s time to do some real work. The welcome screen should look similar to the one below, so just go and create a new free-style-software-project. This is the simplest approach possible, but it’s always nice to get results fast… The job configuration screen should show up now, and it’s time to enter some details.

First of all, we need to setup the SCM section, so Jenkins knows where to get the sources from. Just enter your repos git-URL in the appropriate field. To test the whole thing, you can use any git-hosted project you like that homes a XCode-Project.

If you want, you can run a build now to make sure that the git-setup works correctly, but it isn’t required to do so.

As you can see in the screenshot, the next step is creating the build-phase. You can just enter xcodebuild, which will then build your project and Jenkins will notice if it doesn’t work and display it, but I think it’s more interesting to both build a project and archive the App that was built. To achieve that, I created a simple two-line-command

cd build/Release; zip -r $ *.app/

Jenkins can archive specific artefacts that were created during the build. To save the generated zip-file just enter the **/*.zip pattern in the “Archive Artefacts” field. If you haven’t built your project yet, there may be a big red warning saying that the filter doesn’t match any files, but it’s safe to ignore it.

Of course, this is the most minimal build setup you could use, but for my purposes it’s completely sufficient. The BUILD_TAG used is a unique tag that can be used for filenames. After you’ve saved the changes to the configuration, it’s time to run a build and see if it works.

There are a lot of ways to go from here, but I hope this tutorial helped you to get Jenkins up and running!

flattr this!


242 Kudos

  • Christopher Cotton

    From your page, I was able to figure out the reason for the FileNotFound for the META-INF.  By default when you install, the /Users/Shared/Jenkins is only writeable by root. I just  did  sudo chown daemon:daemon /Users/Shared/Jenkins   and then restarted Jenkins and it all works great now.

    • Anonymous

      Great that it helped you. You maybe want to try the Jenkins-user-approach if you need to do ssh-auth using pubkey, because.. well, there is no daemon home dir, no .ssh dir.. 

  • Simon_n
  • Jan Böhler

    Thx for this article is really helpful !

    is the best how to install Jenkins on OS X tutorial I found… in a short time

  • trent

    Thanks, Got Jenkins up and running.  Had a few configuration problems because I’m a noob with file permissions.  Finally figured to use sudo VI to edit the plist without changing file permissions.  Then everything worked great.

  • Sean

    very helpful, worked as advertised. Thanks!

  • Pingback: Unity3D Jenkins 1- Setup Jenkins | Historyline Remake

  • urmi

    Great article. I am having problem configuring port, I tried java -jar /jenkins/jenkins.war –httpPort=7070, it is showing error and accessing through browser gives 404. Any advise ?

    Thanks in advance

  • Prateek

    I installed jenkins but there is no /Library/LaunchDaemons/org.jenkins-ci.plist file, however the file is in /Library/Preferences.
    How do i add jenkins user?