This guide provides troubleshooting steps for common issues when using Depot-hosted GitHub Actions runners.
When you start a new GitHub job using Depot GitHub Actions runners, you'll notice a brief delay before the runner is ready. This is expected behavior, as typical startup times range from 10 to 45 seconds.
The startup process involves two main steps:
We typically expect GitHub's control plane to take less than 1 second to send a job request to Depot API. We then allocate AWS hardware in approximately 15 seconds. After that, GitHub usually connects to the runner in under 7 seconds, and sends the job to the runner in under a second.
You can check the detailed timing breakdown for the last jobs in your Depot dashboard in the graph at the top of the GitHub Actions page.
We bill only for the time after the job has started running (tracked by the second), not provisioning time.
If you consistently see allocation times longer than 1 minute during normal operation, reach out to support so we can investigate.
If your GitHub Actions workflow remains in a queued state when first setting up Depot runners, this usually means the runner can't be allocated to your job.
Use a single runner label in your workflow configuration. While GitHub Actions supports specifying multiple labels in an array, this can cause stability issues.
Correct usage:
runs-on: depot-ubuntu-24.04-4Avoid using multiple labels:
# Do *not* do this:
runs-on: [self-hosted, depot-ubuntu-24.04]Depot runners register in the "default runner group" in GitHub. Check the repository access settings for the runner group to ensure your repo can use these runners:
Note: If you've configured the Selected workflows filter for your runner group, an incorrect workflow reference pattern can prevent jobs from starting even when runners are available.
The "Depot Managed Runners" GitHub app must have permission to see your repo. You can confirm your app is active in the organization settings under GitHub Actions Runners
If your workflow still gets stuck after checking these settings, reach out to support with your workflow run URL and repository name so we can help investigate the runner allocation issue.
Sometimes jobs may appear as long-running in the Depot dashboard even though they've completed on GitHub. This happens when GitHub doesn't correctly inform our application that a job has finished.
Important: Billing is not affected by stale jobs. We only bill for the time the job actually runs on a runner instance.
Stale jobs will eventually time out on their own. However, if you need immediate resolution, we can manually run a resync with GitHub to clear the job and update the UI to reflect the correct status.
Check the job status directly in your GitHub Actions tab to confirm it has been canceled or completed.
If the job remains stale in the Depot dashboard and you need it cleared immediately, reach out to support with:
We'll trigger a manual resync with GitHub to update the job status.
Failed to write to Depot job log - No space left on deviceThis error occurs when your build process needs more disk space than your runner has available.
Each Depot runner type has a set amount of disk space. The OS and pre-installed software consumes approximately 70 GB, and the remaining space is available for your builds. For runner specifications, see Depot Runner Types.
The most straightforward solution is to use a runner with more disk capacity. You can specify a larger runner type in your workflow configuration:
runs-on: depot-ubuntu-24.04-8 # 8 vCPU, more disk spaceIf you continue to hit disk space limits even on larger runner sizes, reach out to support with your workflow details so we can help optimize your build process or discuss custom runner configurations.
Clean up unnecessary files before and during your build process. For example, you can remove temporary files and clean package caches on Linux workflows:
- name: Clean up disk space
run: |
rm -rf /tmp/*
sudo apt-get cleanSeveral GitHub Actions can help manage disk space automatically. Popular options include actions that remove unused tools, or clear system caches.
The self-hosted runner lost communication with the serverThe following error typically indicates a temporary connectivity issue between the Depot runner and GitHub's servers:
The self-hosted runner lost communication with the server. Verify the machine is running and has a healthy network connection. Anything in your workflow that terminates the runner process, starves it for CPU/Memory, or blocks its network access can cause this error.First, check status.depot.dev for any reported outages. If we're experiencing an incident, please monitor the status page and wait for the resolution. Once we resolve the issue, retry your workflow run.
Next, check the CPU and memory usage of your build process. Open the job details in your Depot dashboard and look at the resource usage graphs at the top of the page. If your build consumes excessive CPU or memory, consider optimizing your build steps to reduce resource consumption.
If you see this error frequently and the resource usage graphs show no issues, reach out to support with your workflow run ID and the approximate time the error occurred. We'll investigate whether there are specific connectivity issues affecting your builds.
Sometimes GitHub Actions workflows become stuck and don't respond to normal cancel requests through the GitHub UI. When this happens, you can use the GitHub REST API to force cancel the workflow run.
This issue is unrelated to Depot, you can read more about it in GitHub's announcement.
Find the run ID of the stuck workflow from your GitHub Actions page. It's in the URL: github.com/{owner}/{repo}/actions/runs/{run_id}
After obtaining the run ID, you can use the GitHub API to attempt a regular cancel:
curl -X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer YOUR_TOKEN" \
https://api.github.com/repos/{owner}/{repo}/actions/runs/{run_id}/cancelIf the workflow doesn't respond, use the force cancel option:
curl -X POST \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer YOUR_TOKEN" \
https://api.github.com/repos/{owner}/{repo}/actions/runs/{run_id}/force-cancelImportant: Use force cancel only when necessary, as it bypasses normal workflow conditions and cleanup steps.
For more details, see GitHub's official REST API documentation.
If you frequently encounter stuck workflows with Depot runners specifically, reach out to support so we can investigate whether there's an underlying issue.
Sometimes you may need to inspect the running environment to diagnose an issue. Depot GitHub Actions runners are compatible with action-tmate, a GitHub Action that allows you to create an SSH session during your workflow run.
action-tmate to your workflowIntegrate action-tmate into your CI pipeline by adding it as a step in your workflow file:
steps:
- uses: actions/checkout@v4
- name: Setup tmate session
uses: mxschmitt/action-tmate@v3
- name: Run tests
run: npm testWhen your job reaches the action-tmate step, open the Checks tab in your Pull Request and scroll to the bottom. You can connect either directly per SSH or via a web based terminal.
Inspect the environment, run commands, and debug as needed. Once done, you can exit the SSH session and let the CI job continue.
For additional information and usage scenarios, visit the action-tmate GitHub page.
Note: Depot does not maintain the action-tmate action. Please report any issues or problems on the project GitHub page.
macOS build jobs may experience longer wait times to start processing when demand is higher than normal.
Apple's licensing requires macOS instances to be leased for a minimum of 24 hours, which results in the following constraints:
For organizations requiring more predictable build times, we offer the option to reserve dedicated macOS runner instances exclusively for your organization. Your jobs run immediately on your dedicated runners when available. If all your dedicated runners are busy processing jobs, additional jobs can still fall back to the shared pool.
Dedicated runners require an annual commitment for fixed capacity tailored to your concurrent job needs.
Contact our support team to learn more about dedicated macOS runners and pricing.
If you can't find a solution in this guide or the Depot GitHub Actions documentation, reach out to our support team.