> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macstadium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jenkins plugin for Orka macOS build agents

> Provision permanent and ephemeral macOS build agents with the Orka Jenkins plugin. Covers plugin installation, agent configuration, and credential setup.

How to use Jenkins with your Orka environment.

The [**Orka by MacStadium plugin for Jenkins**](https://plugins.jenkins.io/macstadium-orka) lets you provision permanent and ephemeral Jenkins agents in your Orka environment.

The provisioning of permanent agents is useful when you need to have complete manual control over the process and the lifecycle of the agents.

The provisioning of ephemeral agents is useful when you need to automatically create and delete agents based on the needs of your workflows.

<Warning>Orka 3.1.x and above requires version [v2.0.0+](https://github.com/jenkinsci/macstadium-orka-plugin/releases/tag/macstadium-orka-2.01) of the plugin. If you are running Orka 2.x, use plugin version 1.35.</Warning>

## Install the Plugin

The Orka by MacStadium plugin is available in the [Jenkins Plugin Manager](https://plugins.jenkins.io/macstadium-orka). For more information about how to install publicly available Jenkins plugins, see [Jenkins Documentation: Managing Plugins](https://jenkins.io/doc/book/managing/plugins/).

If you need to manually build, package, and run the plugin yourself, visit the [plugin repo](https://github.com/jenkinsci/macstadium-orka-plugin) for the latest information.

## Provision Agents with the Plugin

<Warning>Your Jenkins master must be connected to your Orka environment through VPN before provisioning agents. Use a [VPN client](/orka/networking-with-orka-at-macstadium/vpn-connection) for temporary connectivity, or set up a [site-to-site VPN tunnel](/orka/networking-with-orka-at-macstadium/aws-orka-connections) for a persistent connection.</Warning>

The [Orka by MacStadium plugin wiki](https://wiki.jenkins.io/display/JENKINS/Orka+by+MacStadium) provides the latest information about how to use the plugin.

<Note>If you are deploying Apple silicon images for the first time on an ARM-based node, increase the Jenkins agent connection timeout to account for the longer initial boot time.</Note>

## How to Enable Logging for the Orka Plugin for Jenkins

If you're troubleshooting issues with the Orka plugin for Jenkins (current version: [**v2.09**](https://github.com/jenkinsci/macstadium-orka-plugin/releases/tag/macstadium-orka-2.09)), you can enable detailed plugin logging directly from the Jenkins interface using the built-in System Log feature.

## Steps to Enable the Orka Plugin Logger

1. In Jenkins, go to **Manage Jenkins** -> **System Log**.
2. Click **Add new log recorder**.
3. Enter a name for the log recorder (e.g., `Orka Plugin`).
4. Click **Add** under **Loggers**.
5. In the **Logger** field, enter:

```
   io.jenkins.plugins.orka
```

6. Set the **Log Level** to **All**.
7. Click **Save**.

Jenkins will now capture detailed logs for the Orka plugin. You can view them by returning to **Manage Jenkins** → **System Log** and selecting the recorder you created.

## Performance Note

Using the **All** log level is the most verbose setting and can slow down Jenkins. If you notice performance degradation, you can limit logging to the core cloud class instead:

* In the **Logger** field, use:

```
  io.jenkins.plugins.orka.OrkaCloud
```

* Keep the log level set to **All**.

This collects the most relevant logs while reducing overall volume.

## Plugin Requirements

* **Orka by MacStadium 3.0+** -- The current plugin requires Orka 3.0 or later.
* A **VPN connection** to your Orka environment is required. Your Jenkins master must have network visibility to the Orka cluster.

## Need More Help?

If you're still experiencing issues after reviewing the logs, contact [MacStadium Support](mailto:support@macstadium.com) and include the log output for faster troubleshooting.