Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jenkinsci/mac-plugin
Plugin to configure Macs as Jenkins agents
https://github.com/jenkinsci/mac-plugin
groovy jenkins jenkins-agents jenkins-cloud jenkins-plugin jnlp-jenkins-slave keychain macos
Last synced: 3 months ago
JSON representation
Plugin to configure Macs as Jenkins agents
- Host: GitHub
- URL: https://github.com/jenkinsci/mac-plugin
- Owner: jenkinsci
- License: mit
- Created: 2019-10-21T16:30:10.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-08-09T09:17:26.000Z (5 months ago)
- Last Synced: 2024-09-30T08:56:32.399Z (3 months ago)
- Topics: groovy, jenkins, jenkins-agents, jenkins-cloud, jenkins-plugin, jnlp-jenkins-slave, keychain, macos
- Language: Groovy
- Homepage: https://plugins.jenkins.io/mac/
- Size: 422 KB
- Stars: 12
- Watchers: 4
- Forks: 12
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/groupe-edf)
# Mac Plugin
[![Build Status](https://ci.jenkins.io/buildStatus/icon?job=Plugins%2Fmac-plugin%2Fmaster)](https://ci.jenkins.io/job/Plugins/job/mac-plugin/job/master/)
[![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/mac.svg?color=blue)](https://plugins.jenkins.io/mac)
[![Join the chat at https://gitter.im/jenkinsci/mac-plugin](https://badges.gitter.im/jenkinsci/mac-plugin.svg)](https://gitter.im/jenkinsci/mac-plugin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)A good utility to build yours IOS apps, this plugin create MacOs agents for yours builds.
It can stock your Keychains file on Jenkins and send it to the MacOs Nodes.
## Table of Contents
- [Features](#features)
- [Requirements](#requirements)
- [Jenkins](#jenkins)
- [MacOs](#macos)
- [Enable SSH for all users](#enable-ssh-for-all-users)
- [SSH configuration](#ssh-configuration)
- [Configure a Jenkins User](#configure-a-jenkins-user)
- [Plugin configuration](#plugin-configuration)
- [Global Configuration](#global-configuration)
- [Keychain Managment](#keychain-managment)
- [Environment variables](#environment-variables)
- [Pre-launch commands](#pre-launch-commands)
- [Web Socket](#web-socket)
- [User Management Tool](#user-management-tool)
- [Logs configuration](#logs-configuration)
- [Execution](#execution)
- [Troubleshooting](#troubleshooting)
- [Team](#team)
- [Contact](#contact)## Features
- [x] Allow to configure a Mac as Jenkins agent
- [x] Run multiples builds on a single Mac
- [x] Isolates each construction from each other
- [x] Run builds on a cloud of Macs
- [x] Configure environment variables
- [x] Stock keychain file as credentials on Jenkins
- [x] Inject keychain on Node filesystem
- [x] Prepare build environment
- [x] Clean all files created after each buildThis plugin has been tested against macOS 10.14 Mojave and macOS 10.15 Catalina , although theoretically it should work with older version as long as it supports sysadminctl command.
## Requirements
### Jenkins
'TCP port for inbound agents' must be enabled in Global Security settings.
If not, WebSocket must be supported by Jenkins and activated in the agents (see [Web Socket](#web-socket))
### MacOS
**Restart MacOs after configuration change**
#### Enable SSH for all users
Go to System Preferences -> Sharing, and enable Remote Login for All users :#### SSH configuration
In /etc/ssh/sshd_config file, uncomment and update values of parameters MaxAuthTries, MaxSessions, ClientAliveInterval and ClientAliveCountMax to your need.example of configuration for 10 Jenkins and 1 Mac with 10 users allowed :
- MaxAuthTries 10
- MaxSessions 100
- ClientAliveInterval 30
- ClientAliveCountMax 150For more informations about sshd_config consult the
[Official Documentation](https://man.openbsd.org/sshd_config)#### Configure a Jenkins User
Create an user on the Mac with administrator privileges. It will be your connection user for Mac Plugin Global configuration.Add sudo NOPASSWD to this user in /etc/sudoers :
[see how to configure sudo without password](https://www.robertshell.com/blog/2016/12/3/use-sudo-command-osx-without-password)To maximize security, you can configure it only for "chmod" and "sysadminctl" command used by the plugin :
`[USERNAME] ALL = NOPASSWD: /usr/sbin/sysadminctl -addUser mac-?????????? -password ??????????, /usr/sbin/sysadminctl -deleteUser mac-??????????, /bin/chmod -R 700 /Users/mac-??????????/`
**Update for v1.4.0+ :**
Since 1.4.0 it is possible to use "dscl" instead of "sysadminctl". To use the full functionnalities of the plugin, here is the new NOPASSWD configuration for the user :
`[USERNAME] ALL = NOPASSWD: /usr/sbin/sysadminctl -addUser mac-?????????? -password ??????????, /usr/sbin/sysadminctl -deleteUser mac-??????????, /bin/chmod -R 700 /Users/mac-??????????/, /usr/sbin/chown mac-??????????\:staff /Users/mac-??????????, /bin/mkdir /Users/mac-??????????, /usr/bin/dscl . -create /Users/mac-??????????, /usr/bin/dscl . -create /Users/mac-?????????? UserShell /bin/zsh, /usr/bin/dscl . -create /Users/mac-?????????? UniqueID ???, /usr/bin/dscl . -create /Users/mac-?????????? PrimaryGroupID 20, /bin/cp -R /System/Library/User\ Template/Non_localized /Users/mac-??????????, /bin/cp -R /System/Library/User\ Template/English.lproj /Users/mac-??????????, /usr/bin/dscl . -create /Users/mac-?????????? NFSHomeDirectory /Users/mac-??????????, /usr/sbin/chown -R mac-??????????\:staff /Users/mac-??????????, /usr/bin/dscl . -passwd /Users/mac-?????????? ??????????, /usr/bin/pkill -u mac-??????????, /usr/bin/dscl . -delete /Users/mac-??????????, /bin/rm -rf /Users/mac-??????????`
## Plugin configuration
### Global Configuration
In jenkins global configuration, add a new Mac Cloud :Configure fields of Mac Cloud :
Select JNLP for the connector and refer your Jenkins URL. This URL must be accessible by outside, localhost is not working.
Add a new Mac Host and fill the properties in the fields :
The number of simultaneous builds on the same Mac Host depends of the property "Max users".
More you have Mac Hosts configured, more you can build simultaneous on many machines.
**The plugin was tested with a limit of 7 users per Mac hosts.**The supported credentials for now is User and Password.
Put an account of your mac with **sudo NOPASSWORD configured** (see Configure a Jenkins User).Refer the label of your agent.
Select JNLP for the connector and refer your Jenkins URL. This URL must be accessible by outside, localhost is not working.In a project configuration, refers the label :
### Keychain Managment
Since v1.1.0, you have the possibility to stock keychain files into Jenkins to inject it in the Jenkins Mac agent.
For this, check "Upload a keychain file" :Add a new Secret file credentials. **Prefers to store it as System Credentials to not allow any project to use it directly** :
The Keychain will be send to the Mac agent with SCP in ~/Library/Keychains/ directory before the JNLP connection.
### Environment variables
Since v1.1.0, you can set environment variables on Mac host. Theses variables will be set on the Node and will be accessible in the build.### Pre-launch commands
Since v1.3.0, you can set commands passed to the user before the agent starts.
The field is a multi-line string, and each line match to a command execution.
It is possible to run a script on the Mac with this field.### Web Socket
Since v1.3.1, Mac agents supports [WebSocket](https://www.jenkins.io/blog/2020/02/02/web-socket/).The option is available in Mac Cloud settings :
### User Management Tool
v1.4.0 include the possibility to choose between "sysadminctl" or "dscl" for the users creation and deletion.The option is available in Mac Cloud->Mac Host settings :
This functionality has been developed to fix [JENKINS-66374](https://issues.jenkins.io/browse/JENKINS-66374)
sudoers file on the Mac must be updated to add sudo NOPASSWD on all commands needed to create the user with dscl (see [Configure a Jenkins User](#configure-a-jenkins-user)).
## Logs configuration
You can define a custom LOGGER to log every output of the plugin on the same place.
To do it, go to System logs in the Jenkins configuration :Configure the Logger of the plugin :
Save your configuration.
## Execution
After configuration, when you run a job with a Mac Cloud label, it will create a jenkins agent on the mac you setted as host and run the build on it.You can see it on the home page of Jenkins :
## Troubleshooting
* Zombie process : Sometimes, "sysadminctl" tool continue to run after task executed. After a while, it can saturate MacOS (in our case we had +1000 process running). To prevent this, a script with the command "killall sysadminctl" has to be run regulary.
* User and homedirs not deleted : Sometimes when an error happens, the users and/or home directories cannot be deleted. This issue can block the others builds because the plugin detect the user like a build in progress and will wait until its deletion. A clean of the users and homedirs starting with "mac-" has to be run regulary.**Recommendation :**
All Mac used with the plugin has to be rebooted at least one time a week to prevent theses problems. This script can be run during the reboot to clean all uneeded users and process :```
killall sysadminctl
for user in `/usr/bin/dscl . -list /Users | grep mac-`; do
/usr/bin/dscl . -delete /Users/$user
donecd /Users/ && ls | grep mac- | xargs rm –rf
```Since v1.4.0, it is possible to use dscl over sysadminctl (see [User Management Tool](#user-management-tool)). Theses issues should not happen with dscl.
## Team
Product Owner : [Cloudehard](https://github.com/Cloudehard)
Developer : [mat1e](https://github.com/mat1e)
## Contact
Any question ? You can ask it on the [Gitter room](https://gitter.im/jenkinsci/mac-plugin) or open an issue on the [Jira of Jenkins](https://issues.jenkins-ci.org/secure/Dashboard.jspa).