Connection · Migration · CI/CD

How to Troubleshoot: From Connection Checks to Pipeline Recovery

First identify which layer is affected, then collect the node, timestamp, complete error, and most recent change. This checklist covers ArmMacs Cloud Mac graphical interfaces, command line, Xcode, and self-hosted Runners.

Open a technical support ticket in the console View first-connection steps
diagnostic-checklist

01 Identify the node and model

02 Record the local network state

03 Reproduce once with a timestamp

04 Collect sanitized logs

05 Attach evidence to the ticket

Fully functional graphical interface and command line Dedicated physical node, not a virtual machine Runs reliably 365 days a year

Support routing

Start by routing the issue

The same symptom may come from your local network, the node system, the toolchain, or pipeline configuration. Choose the closest category first, and record the affected node, local time and time zone, exact error text, and most recent successful run.

Unable to connect

For VNC, SSH, rejected credentials, connection timeouts, or sessions that disconnect unexpectedly. First distinguish between an unreachable target and an authentication failure.

Required: node · protocol · timestamp

Development environment

For Xcode versions, command-line tools, dependency resolution, signing-material permissions, build caches, and disk-space issues.

Required: version · command · exact error

CI/CD

For offline Runners, mismatched labels, queued jobs, concurrency conflicts, workspace contamination, or failed post-build cleanup.

Required: job ID · labels · Runner logs

Storage

For insufficient space, growing build artifacts, cache usage, data migration, external backups, and exports before the rental period ends.

Required: free space · path · data volume

Billing

For order status, rental periods, renewals, and payment records. Orders are billed in USD; only the specified payment methods are supported.

Required: order number · amount · payment time

Keep the exact error text; do not write only “it doesn’t work.” Before submitting logs, remove passwords, private keys, access tokens, signing material, and business data from repositories.

First connection

Complete the first connection in four steps

Do not change the network, credentials, and system settings at the same time. Verify each step before continuing so you can identify exactly where a problem occurs.

  1. 01

    Retrieve and verify credentials

    Open the relevant order in the console and verify the model, node, connection address, username, temporary password, or SSH credentials. Confirm that you are viewing the target instance, not an expired order or an order in another region. Store credentials only in a controlled password manager.

  2. 02

    Verify the local network path to the node

    Record the local network type, egress environment, and test time first. Then check DNS resolution, reachability of the target address, and required ports. If the company network fails but a backup network works, check the local firewall, proxy, or egress policy first rather than repeatedly resetting the node.

  3. 03

    Establish a VNC or SSH connection

    Use VNC remote desktop access when you need a graphical interface; prefer SSH for scripts, repository synchronization, and automation. Start with a short session to verify keyboard input, file read/write access, and command execution before migrating large datasets or installing dependencies.

  4. 04

    Change the initial security settings

    Change the temporary password immediately, configure SSH public keys according to your team’s policy, limit credential visibility, and review remote-access settings. Never place private keys, certificate passphrases, or pipeline tokens in shared scripts, build logs, or repository files.

Connection evidence

Record at least this information when a connection fails

node: SG / JP / KR / HK / US-W
protocol: VNC or SSH
local_network: office / home / mobile
timestamp: YYYY-MM-DD HH:MM timezone
result: timeout / refused / authentication failed
last_success: YYYY-MM-DD HH:MM timezone

Migration path

From a local Mac to a reproducible pipeline

Migration does not mean copying the entire user directory. Handle project data, toolchain definitions, and Runner configuration separately to reduce environment drift and support a complete export before the rental period ends.

PATH 01

Migrate project data

  1. Define the scopeMigrate only repositories, required datasets, configuration templates, and build inputs; do not copy unrelated caches.
  2. Calculate the sizeRecord the source directory size, file count, and checksums, and reserve space for dependencies and build artifacts.
  3. Transfer in batchesVerify permissions and line endings with small repositories first. Split large datasets by directory and spot-check them after transfer.
  4. Isolate secretsConfigure sensitive credentials separately through controlled means. Keep them out of archives, repositories, and ordinary synchronization directories.
PATH 02

Reproduce Xcode and dependencies

  1. Pin versionsRecord the versions of Xcode, command-line tools, language runtimes, and package managers.
  2. Restore dependenciesPrefer lockfiles and executable installation scripts; do not copy local build caches directly.
  3. Run a baseline buildBuild the smallest target first, then run tests and a complete archive. Save exit codes and logs separately.
  4. Capture the checklistDocument versions, installation order, environment-variable names, and verification commands in the team runbook.
PATH 03

Integrate a CI/CD Runner

  1. Create a dedicated execution environmentSeparate pipeline jobs from everyday remote desktop use to reduce permission and workspace conflicts.
  2. Set precise labelsLabels should at minimum identify the platform, chip tier, and major Xcode version to prevent jobs from being routed incorrectly.
  3. Start with one concurrent jobVerify builds, tests, archives, and artifact uploads first, then assess whether concurrency is needed.
  4. Define cleanup actionsRemove temporary credentials, derived data, and unused artifacts after each job while retaining required logs.

Xcode diagnostics

Troubleshoot Xcode Cloud builds layer by layer

Confirm the toolchain first, then check permissions, caches, and storage. Do not upgrade Xcode, update dependencies, and replace signing files in the same retry; otherwise the logs cannot show which change resolved the issue.

Check layer Facts to verify Recommended action Ticket evidence
Version selection Whether the Xcode GUI version, command-line tools path, and SDK required by the project are consistent Pin one version for a minimal build and confirm that the pipeline and interactive terminal use the same path Version output, selected path, failed target
Signing files Whether files are complete, current, and correctly referenced by the target and configuration Verify file readability in an isolated environment without writing sensitive content to logs Sanitized name, expiration date, exact error
Certificate permissions Whether the build user can access the required certificates and key material Compare the permission environments of the interactive build and Runner user to narrow the difference Execution user, permission result, failed stage
Derived Data Whether old caches came from another branch, Xcode version, or build configuration Save one failed log, clear the target cache, and run the same command again for comparison Exit codes and log differences before and after cleanup
Disk space Free space on the system volume, archive directories, simulator data, and dependency-cache usage Delete regenerable caches and expired artifacts first; do not delete the only copy Free space before failure and largest directory
Build logs Whether the first real error, failed target, exit code, and surrounding context are complete Save the raw text log, capture the relevant lines around the first error, and sanitize them Command, timestamp, exit code, log attachment

Keep only the context needed to locate the issue. Before submitting, search for and remove tokens, passwords, private keys, certificate passphrases, internal repository URLs, and business data.

Runner handbook

Baseline for integrating and cleaning up both Runner types

ArmMacs provides dedicated physical nodes, so workspaces and toolchains can persist across builds. Persistence also means caches, credentials, and old artifacts do not disappear automatically; define cleanup boundaries explicitly in the pipeline.

GitHub Actions

Self-hosted Mac Runner

  1. RegistrationRegister with a dedicated Runner identity, confirm that the service remains online after startup, and record the Runner name and working directory.
  2. LabelsKeep the platform label and add chip tier, major Xcode version, and purpose labels. Workflows should match only the label combination they actually need.
  3. ConcurrencyRun jobs serially at first. Multiple Xcode archives running simultaneously compete for disk, caches, and signing resources, increasing intermittent failures.
  4. CleanupDelete temporary credentials and job-level files after each job. Retain caches within key and capacity limits, and remove expired local copies after a successful archive upload.
GitLab CI

macOS Runner

  1. RegistrationDefine the Runner’s scope and execution mode, verify the build user’s directory permissions, and save the registration time and configuration summary.
  2. LabelsSet labels for macOS, chip tier, major Xcode version, and job type. Prevent unlabeled jobs from occupying a dedicated node.
  3. ConcurrencySet initial concurrency to 1. Increase it only after job directories, ports, caches, and signing materials are fully isolated.
  4. CleanupAt the end of each job, clean secret files and temporary artifacts from the workspace. Failed jobs must also run cleanup, with sanitized logs retained separately.

Minimum pre-launch validation matrix

checkout ✓ dependency restore ✓ build ✓ test ✓ artifact export ✓ secret cleanup ✓

Remote desktop

For remote desktop issues, first separate display, input, and session problems

VNC performance depends on the local network, cross-region routing, resolution, and the frequency of visual changes. When an issue occurs, record the node and local network state, then change one variable for comparison.

What to do about display lag or choppy scrolling

Record the node, local network type, test time, and whether a proxy is present. First lower the remote desktop resolution and image quality, disable constantly changing animations or video, and compare input response. If a backup network clearly improves performance, check local egress congestion or policy. If multiple networks perform the same way at the same time, submit the node and timestamp.

What to do about a mismatched resolution or abnormal UI scaling

Set a common resolution in a single-monitor setup first, disconnect, and start a new session. Confirm that client scaling and remote display settings are not both enlarging the image. When recording the issue, retain both the client window dimensions and the remote resolution values.

What to do about inconsistent shortcuts or symbol input

Check the keyboard layouts locally and remotely, then test letters, numbers, symbols, and modifier keys in a plain-text editor. If the issue occurs only in a specific application, record its name and the shortcut. If every application is affected, include both layouts and the client version.

Should I restart the node immediately after a session disconnects?

Do not restart it immediately. First check whether the local network switched, the device went to sleep, or VNC disconnected while SSH remains available, and record the interruption time. If SSH is accessible, save the work state and relevant logs first. If neither protocol is reachable, submit a ticket through the console.

What information should I retain before reconnecting?

Retain the node, protocol, local network, client version, last successful time, interruption time, and exact error. Change only one condition when reconnecting, such as switching networks or lowering the resolution, and record the result so the comparison remains valid.

Storage responsibility

Storage, backups, and exports before the rental period ends

A workspace on a physical node is suitable for builds and experiments, but it should not be the only copy of code, certificates, models, or build artifacts. The user team must include data migration, external backups, and final export in its project plan.

01

Classify data before migration

Classify data into four groups: recoverable from the repository, reproducible from dependency sources, requiring backup, and prohibited from upload. Estimate peak capacity for the project, dependencies, Derived Data, archives, and logs; do not look only at source-code size.

02

Create an external backup snapshot

Store critical code, certificates, models, datasets, and final artifacts in an external backup location controlled by the team. Perform periodic restore checks to confirm the backup contains usable content, not just a file list.

03

Manage sensitive credentials

Configure credentials with least-privilege access and distinguish between human and pipeline use. Do not write them to shell history, repositories, ordinary environment files, or build artifacts; delete old copies promptly after rotation.

04

Control cache growth

Set retention rules for dependency caches, Derived Data, simulator data, and archives. Confirm content is reproducible before deleting it; when storage is low, handle expired caches and uploaded artifacts first.

Before expiry

Checklist before the rental period ends

  • Export unpushed code, datasets, models, archives, and test results
  • Verify file counts, sizes, and key checksums in external copies
  • Stop the Runner and remove the corresponding execution node from the pipeline
  • Revoke tokens, SSH key authorization, and temporary access credentials
  • Delete business data, secret files, and no-longer-needed logs from the node
  • Check the rental period, renewal status, and order end time in the console

Support ticket

Submit a ticket that can be reproduced directly

If a rented node fails, sign in to the console and submit a ticket first. The console links the issue to the order, making it easier to verify the model, node, and delivery status. If you cannot access the console, email support@armmacs.com.

Open a support ticket in the console Email support
ticket-evidence.txt 
Order number:
Model:
Node:
Issue type:
Time and time zone:
Last successful time:
Reproduction steps:
Expected result:
Actual result:
Exact error:
Most recent configuration change:
Local network state:
Attachments: sanitized logs / screenshots

Make reproduction steps executable

Write the connection method, commands, target project, and failed stage in the actual order. If the issue is intermittent, state its frequency and the comparison conditions already tested.

Always include the time zone with timestamps

Use the full date, hour, minute, and time zone. “Just now” or “today” cannot be matched accurately to node events and Runner logs.

Sanitize attachments first

Screenshots and logs must not contain passwords, private keys, tokens, certificate passphrases, or business data. Retain the exact error, exit code, and necessary context.

Ready for diagnosis

The node, timestamp, and logs are ready

Sign in to the console, link the order, and submit a ticket. Billing is in USD only; supported methods are USDT-TRC20 and Visa / Mastercard / Amex (via Stripe). Actual gateway availability is determined by the console response.

Submit a technical support ticket now Rent a cloud Mac now