{"id":15045627,"url":"https://github.com/jenkinsci/mac-plugin","last_synced_at":"2025-10-26T15:50:19.335Z","repository":{"id":42573267,"uuid":"216615031","full_name":"jenkinsci/mac-plugin","owner":"jenkinsci","description":"Plugin to configure Macs as Jenkins agents","archived":false,"fork":false,"pushed_at":"2025-02-13T10:50:16.000Z","size":435,"stargazers_count":12,"open_issues_count":2,"forks_count":12,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-06T01:51:09.736Z","etag":null,"topics":["groovy","jenkins","jenkins-agents","jenkins-cloud","jenkins-plugin","jnlp-jenkins-slave","keychain","macos"],"latest_commit_sha":null,"homepage":"https://plugins.jenkins.io/mac/","language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-21T16:30:10.000Z","updated_at":"2025-04-04T04:17:52.000Z","dependencies_parsed_at":"2024-09-25T01:58:21.496Z","dependency_job_id":"b2e8aaab-9469-431d-b3da-33fc9ab97a40","html_url":"https://github.com/jenkinsci/mac-plugin","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/jenkinsci/mac-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fmac-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fmac-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fmac-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fmac-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/mac-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fmac-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262419748,"owners_count":23308098,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["groovy","jenkins","jenkins-agents","jenkins-cloud","jenkins-plugin","jnlp-jenkins-slave","keychain","macos"],"created_at":"2024-09-24T20:52:06.028Z","updated_at":"2025-10-26T15:50:14.274Z","avatar_url":"https://github.com/jenkinsci.png","language":"Groovy","funding_links":[],"categories":[],"sub_categories":[],"readme":"[\u003cimg src=\"https://i.pinimg.com/originals/bc/00/a8/bc00a8bd0a4be6cd29680d02c70f0539.png\" width=\"100\" align=\"right\"/\u003e](https://github.com/groupe-edf)\n\n# Mac Plugin\n[![Build Status](https://ci.jenkins.io/buildStatus/icon?job=Plugins%2Fmac-plugin%2Fmaster)](https://ci.jenkins.io/job/Plugins/job/mac-plugin/job/master/)\n[![Jenkins Plugin Installs](https://img.shields.io/jenkins/plugin/i/mac.svg?color=blue)](https://plugins.jenkins.io/mac)\n[![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\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nA good utility to build yours IOS apps, this plugin create MacOs agents for yours builds.\n\nIt can stock your Keychains file on Jenkins and send it to the MacOs Nodes.\n\n## Table of Contents\n- [Features](#features)\n- [Requirements](#requirements)\n    - [Jenkins](#jenkins)\n    - [MacOs](#macos)\n       - [Enable SSH for all users](#enable-ssh-for-all-users)\n       - [SSH configuration](#ssh-configuration)\n       - [Configure a Jenkins User](#configure-a-jenkins-user)\n- [Plugin configuration](#plugin-configuration)\n    - [Global Configuration](#global-configuration)\n    - [Keychain Managment](#keychain-managment)\n    - [Environment variables](#environment-variables)\n    - [Pre-launch commands](#pre-launch-commands)\n    - [Web Socket](#web-socket)\n    - [User Management Tool](#user-management-tool)\n- [Logs configuration](#logs-configuration)\n- [Execution](#execution)\n- [Troubleshooting](#troubleshooting)\n- [Team](#team)\n- [Contact](#contact)\n\n## Features\n\n- [x] Allow to configure a Mac as Jenkins agent\n- [x] Run multiples builds on a single Mac\n- [x] Isolates each construction from each other\n- [x] Run builds on a cloud of Macs\n- [x] Configure environment variables\n- [x] Stock keychain file as credentials on Jenkins\n- [x] Inject keychain on Node filesystem\n- [x] Prepare build environment\n- [x] Clean all files created after each build\n\nThis 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.\n\n## Requirements\n\n### Jenkins\n\n'TCP port for inbound agents' must be enabled in Global Security settings.\n\nIf not, WebSocket must be supported by Jenkins and activated in the agents (see [Web Socket](#web-socket))\n\n### MacOS\n\n**Restart MacOs after configuration change**\n\n#### Enable SSH for all users\nGo to System Preferences -\u003e Sharing, and enable Remote Login for All users :\n\n\u003cimg src=\"https://zupimages.net/up/19/47/q7yq.png\" width=\"500\"/\u003e\n\n#### SSH configuration\nIn /etc/ssh/sshd_config file, uncomment and update values of parameters MaxAuthTries, MaxSessions, ClientAliveInterval and ClientAliveCountMax to your need.\n\nexample of configuration for 10 Jenkins and 1 Mac with 10 users allowed :\n\n- MaxAuthTries 10\n- MaxSessions 100\n- ClientAliveInterval 30\n- ClientAliveCountMax 150\n\nFor more informations about sshd_config consult the\n[Official Documentation](https://man.openbsd.org/sshd_config)\n\n#### Configure a Jenkins User\nCreate an user on the Mac with administrator privileges. It will be your connection user for Mac Plugin Global configuration.\n\nAdd sudo NOPASSWD to this user in /etc/sudoers :\n[see how to configure sudo without password](https://www.robertshell.com/blog/2016/12/3/use-sudo-command-osx-without-password)\n\nTo maximize security, you can configure it only for \"chmod\" and \"sysadminctl\" command used by the plugin :\n\n`[USERNAME] ALL = NOPASSWD: /usr/sbin/sysadminctl -addUser mac-?????????? -password ??????????, /usr/sbin/sysadminctl -deleteUser mac-??????????, /bin/chmod -R 700 /Users/mac-??????????/`\n\n**Update for v1.4.0+ :**\n\nSince 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 :\n\n`[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-??????????`\n\n## Plugin configuration\n### Global Configuration\nIn jenkins global configuration, add a new Mac Cloud :\n\n\u003cimg src=\"https://www.zupimages.net/up/19/47/e599.png\" width=\"200\"/\u003e\n\nConfigure fields of Mac Cloud :\n\n\u003cimg src=\"https://zupimages.net/up/19/47/d1i6.png\" width=\"750\"/\u003e\n\nSelect JNLP for the connector and refer your Jenkins URL. This URL must be accessible by outside, localhost is not working.\n\nAdd a new Mac Host and fill the properties in the fields :\n\n\u003cimg src=\"https://zupimages.net/up/19/47/vrte.png\" width=\"750\"/\u003e\n\nThe number of simultaneous builds on the same Mac Host depends of the property \"Max users\".\nMore you have Mac Hosts configured, more you can build simultaneous on many machines.\n**The plugin was tested with a limit of 7 users per Mac hosts.**\n\nThe supported credentials for now is User and Password.\nPut an account of your mac with **sudo NOPASSWORD configured** (see Configure a Jenkins User).\n\nRefer the label of your agent.\nSelect JNLP for the connector and refer your Jenkins URL. This URL must be accessible by outside, localhost is not working.\n\nIn a project configuration, refers the label :\n\n\u003cimg src=\"https://zupimages.net/up/19/47/xyw2.png\" width=\"750\"/\u003e\n\n### Keychain Managment\nSince v1.1.0, you have the possibility to stock keychain files into Jenkins to inject it in the Jenkins Mac agent.\nFor this, check \"Upload a keychain file\" :\n\n\u003cimg src=\"https://zupimages.net/up/19/49/93el.png\" width=\"400\"/\u003e\n\nAdd a new Secret file credentials. **Prefers to store it as System Credentials to not allow any project to use it directly** :\n\n\u003cimg src=\"https://zupimages.net/up/19/49/xw7u.png\" width=\"750\"/\u003e\n\nThe Keychain will be send to the Mac agent with SCP in ~/Library/Keychains/ directory before the JNLP connection.\n\n### Environment variables\nSince 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.\n\n\u003cimg src=\"https://zupimages.net/up/19/50/i14g.png\" width=\"650\"/\u003e\n\n### Pre-launch commands\nSince v1.3.0, you can set commands passed to the user before the agent starts.\nThe field is a multi-line string, and each line match to a command execution.\nIt is possible to run a script on the Mac with this field.\n\n\u003cimg src=\"https://zupimages.net/up/21/23/05ub.png\" width=\"750\"/\u003e\n\n### Web Socket\nSince v1.3.1, Mac agents supports [WebSocket](https://www.jenkins.io/blog/2020/02/02/web-socket/).\n\nThe option is available in Mac Cloud settings :\n\n\u003cimg src=\"https://zupimages.net/up/21/31/nn4a.png\" width=\"800\"/\u003e\n\n### User Management Tool\nv1.4.0 include the possibility to choose between \"sysadminctl\" or \"dscl\" for the users creation and deletion.\n\nThe option is available in Mac Cloud-\u003eMac Host settings :\n\n\u003cimg src=\"https://zupimages.net/up/21/47/zrdb.png\" width=\"800\"/\u003e\n\nThis functionality has been developed to fix [JENKINS-66374](https://issues.jenkins.io/browse/JENKINS-66374)\n\nsudoers 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)).\n\n## Logs configuration\nYou can define a custom LOGGER to log every output of the plugin on the same place.\nTo do it, go to System logs in the Jenkins configuration :\n\n\u003cimg src=\"https://zupimages.net/up/19/47/m7i5.png\" width=\"400\"/\u003e\n\nConfigure the Logger of the plugin :\n\n\u003cimg src=\"https://zupimages.net/up/19/47/3mkc.png\" width=\"750\"/\u003e\n\nSave your configuration.\n\n## Execution\nAfter 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.\n\nYou can see it on the home page of Jenkins :\n\n\u003cimg src=\"https://zupimages.net/up/19/47/fkmf.png\" width=\"300\"/\u003e\n\n## Troubleshooting\n* 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.\n* 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.\n\n**Recommendation :**\nAll 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 :\n\n```\nkillall sysadminctl\nfor user in `/usr/bin/dscl . -list /Users | grep mac-`; do\n    /usr/bin/dscl . -delete /Users/$user\ndone\n\ncd /Users/ \u0026\u0026 ls | grep mac- | xargs rm –rf\n```\n\nSince 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.\n\n## Team\n\nProduct Owner : [Cloudehard](https://github.com/Cloudehard)\n\nDeveloper : [mat1e](https://github.com/mat1e)\n\n## Contact\nAny 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).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fmac-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fmac-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fmac-plugin/lists"}