About troubleshooting workflows

Initial troubleshooting suggestions

There are several ways you can troubleshoot failed workflow runs.

Using GitHub Copilot

If a workflow run fails, you can open a chat with GitHub Copilot for assistance resolving the error. See Использование Copilot для устранения неполадок рабочих процессов.

Using workflow run logs

Each workflow run generates activity logs that you can view, search, and download. For more information, see Использование журналов выполнения рабочих процессов.

Enabling debug logging

If the workflow logs do not provide enough detail to diagnose why a workflow, job, or step is not working as expected, you can enable additional debug logging. For more information, see Включение ведения журналов отладки.

If your workflow uses specific tools or actions, enabling their debug or verbose logging options can help generate more detailed output for troubleshooting. For example, you can use npm install --verbose for npm or GIT_TRACE=1 GIT_CURL_VERBOSE=1 git ... for git.

Reviewing billing errors

Actions usage includes runner minutes and storage for workflow artifacts. For more information, see Сведения о выставлении счетов за GitHub Actions.

Setting a budget

Setting an Actions budget may help immediately unblock workflows failing due to billing or storage errors. It will allow further minutes and storage usage to be billed up to the set budget amount. To learn more, see Использование бюджетов для контроля расходов на лимитные продукты.

Reviewing GitHub Actions activity with metrics

To analyze the efficiency and reliability of your workflows using metrics, see Просмотр метрик GitHub Actions.

Troubleshooting workflow triggers

You can review your workflow’s on: field to understand what is expected to trigger the workflow. For more information, see Активация рабочего процесса.

For a full list of available events, see События, инициирующие рабочие процессы.

Triggering event conditions

Some triggering events only run from the default branch (i.e. issues, schedule). Workflow file versions that exist outside of the default branch will not trigger on these events.

Workflows will not run on pull_request activity if the pull request has a merge conflict.

Workflows that would otherwise be triggered on push or pull_request activity will be skipped if the commit message contains a skip annotation. For more information, see Пропуск запусков рабочих процессов.

Scheduled workflows running at unexpected times

Scheduled events can be delayed during periods of high loads of GitHub Actions workflow runs.

High load times include the start of every hour. If the load is sufficiently high enough, some queued jobs may be dropped. To decrease the chance of delay, schedule your workflow to run at a different time of the hour. For more information, see События, инициирующие рабочие процессы.

Filtering and diff limits

Specific events allow for filtering by branch, tag, and/or paths you can customize. Workflow run creation will be skipped if the filter conditions apply to filter out the workflow.

You can use special characters with filters. For more information, see Синтаксис рабочего процесса для GitHub Actions.

For path filtering, evaluating diffs is limited to the first 300 files. If there are files changed that are not matched in the first 300 files returned by the filter, the workflow will not be run. For more information, see Синтаксис рабочего процесса для GitHub Actions.

Troubleshoot workflow execution

Workflow execution involves any issues seen after the workflow was triggered and a workflow run has been created.

Canceling Workflows

If standard cancellation through the UI or API does not process as expected, there may be a conditional statement configured for your running workflow job(s) that causes it to not cancel.

In these cases, you can leverage the API to force cancel the run. For more information, see Конечные точки REST API для выполнения рабочих процессов.

A common cause can be using the always() status check function which returns true, even on cancellation. An alternative is to use the inverse of the cancelled() function, ${{ !cancelled() }}.

For more information, see Использование условий для управления выполнением задания and Отмена рабочего процесса.