Skip to main content

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.

How to get started with your preferred CI/CD integration. Learn how to set it up for the first time and how to get help.

​
The Ultimate Quick Start

If you want to skip the detailed explanations, just run through these steps on your own:
  1. Review the list of available integrations at Orka Tools & Integrations and select the one you want to use.
  2. Create a service account and get a token.
  3. List the available VMs and images.
  4. Create a VM config for your workflow with the CLI.
  5. Complete the CI/CD integration setup as per its instructions.
Orka provides many integrations and plugins to set up a CI/CD pipeline with your preferred service provider. You can also build an in-house CI/CD integration with the Orka3 CLI or the Orka3 API. This page focuses on the ready CI/CD solutions for Orka. The Orka CI/CD integrations are most useful if you have:
  • Basic Orka knowledge and basic or advanced knowledge about your preferred CI/CD provider
  • Workflows that require automation
Most CI/CD integrations rely on SSH to connect to the VM where your builds run and provide both permanent and ephemeral build agent options.
  • Permanent build agent: A running VM that persists between pipeline iterations. The VM is never destroyed and the pipeline reuses it on every run.
  • Ephemeral build agent: A VM that spins up for the duration of one pipeline run and is destroyed after.

​
1. Before You Begin

  1. Make sure you can access the account for your cluster in the MacStadium Customer Portal. See Cluster Access Management: Overview.
  2. Get your VPN connection information from your IP Plan. You can download it from the MacStadium portal.
  3. Connect to your Orka cluster via VPN. Make sure that your CI/CD integration can reach the cluster via VPN.
    1. Download and install a VPN client. Note that if you’re using a custom Orka domain, you might need to make some additional configuration changes.
    2. Use the server address and credentials from the VPN section at the top of your IP Plan.
  4. Install the Orka3 CLI on your system.

​
2. Some Orka CI/CD Basics

  • CI/CD integrations must target your Orka API URL. If you are using an Orka domain or an external custom domain, you must ensure that the CI/CD integration can resolve the domain.
What’s your Orka API URL? You can get your Orka API URL from your IP Plan:
  • For clusters deployed before Orka 2.1, it’s the .100 address for your Private-1 network (usually, 10.221.188.100), prefixed with http. For example: http://10.221.188.100.
  • For clusters deployed with Orka 2.1 or later, it’s the .20 address for your Private-1 network (usually 10.221.188.20), prefixed with http. For example: http://10.221.188.20.
  • You can also use https://<orka-domain> and https://<custom-domain> (if configured). To get the Orka domain for your Orka cluster, contact MacStadium support. To use an external custom domain, see here.
Note that you can use http://<orka-IP>, https://<orka-domain>, and https://<custom-domain> interchangeably in your workflows.

​
3. Pick Your CI/CD Integration

Go to Orka Tools & Integrations and review the latest list of available integrations. Pick the one you want to use and navigate to its detailed setup instructions (usually available in the respective repo or official integration page).

​
4. Create a Service Account and Get a Token

Orka clusters now require authentication via Single Sign-On or via service account token. Service accounts are intended for use with CI/CD integrations. They don’t require username/password credentials to log in and let CI/CD integrations bypass the browser login via the Orka3 CLI. The tokens for service accounts also have an extended duration of 1 year. 
# Create the service account
orka3 sa create <SERVICE_ACCOUNT_NAME>

# Generate a token: copy this and store it as a secret in your CI/CD system
orka3 sa token <SERVICE_ACCOUNT_NAME>
Grab the token from the output of orka3 sa token and store it as a secret in your CI/CD system. Use it to authenticate the integration with your Orka cluster. These commands create a service account in the orka-default namespace and obtain a valid token for it. If you need your CI/CD integration to be able to work in additional namespaces, you need to create the service account in the respective namespace or configure the respective role bindings.

​
5. Create the Template for Your Permanent or Ephemeral Agent

  1. Check if there are any VM configs on your environment.
orka3 vm-config list
  1. List the available base images:
orka3 image list
MacStadium maintains a public OCI registry at ghcr.io/macstadium/orka-images with pre-built macOS images. You don’t need to pull images manually — you can reference them directly in your VM config.
  1. Create your first VM config:
orka3 vmc create <NAME> --image ghcr.io/macstadium/orka-images/sonoma:latest --cpu 4
VM config name requirements: The name must not exceed 50 characters, consist of lowercase alphanumeric characters or dashes (-), start with an alphabetic character, and end with an alphanumeric character. The name must be unique in the cluster.
Your CI/CD pipeline will use this VM config to spin up permanent or ephemeral agents. Every agent is a deployed VM instance of a VM config.
If you’re using a custom image or installing from ISO, SSH or Screen Sharing may not be enabled by default. In that case, connect via VNC first, then enable them in the OS.

​
6. Complete the CI/CD Setup

Revisit the setup instructions for your preferred Orka CI/CD integration. Fill in any configuration fields as needed. Note that you might need to provide the SSH credentials for the VM.
By default, MacStadium’s official images use admin/admin credentials. Change this after first login.

​
Next Steps

Pick your integration and follow the guide for your CI/CD platform: Not sure which to use? See Tools and Integrations for the full list.