Flux de travail de résolution des problèmes

Initial troubleshooting suggestions

There are several ways you can troubleshoot failed workflow runs.

Remarque

If you are on a GitHub Copilot Free subscription, this will count towards your monthly chat message limit.

Using GitHub Copilot

To open a chat with GitHub Copilot about a failed workflow run, you can either:

Next to the failed check in the merge box, click , then click Explain error.
In the merge box, click on the failed check. At the top of the workflow run summary page, click Explain error.

This opens a chat window with GitHub Copilot, where it will provide instructions to resolve the issue.

Using workflow run logs

Each workflow run generates activity logs that you can view, search, and download. For more information, see Utilisation des journaux d’exécution de flux de travail.

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 Activation de la journalisation du débogage.

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 Facturation des actions GitHub.

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 Configurer des budgets pour contrôler les dépenses liées aux produits facturés à l’usage.

Reviewing GitHub Actions activity with metrics

To analyze the efficiency and reliability of your workflows using metrics, see Affichage des mesures des GitHub Actions.

Troubleshooting workflow triggers

First, make sure that your workflow wasn't disabled manually, see Désactivation et activation d’un workflow. A disabled workflow does not respond to its triggers.

You can review your workflow's on: field to understand what is expected to trigger the workflow. For more information, see Déclenchement d’un workflow.

For a full list of available events, see Événements qui déclenchent des flux de travail.

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 Exécutions de workflow ignorées.

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 Événements qui déclenchent des flux de travail.

Scheduled workflow stopped running

A scheduled (cron) workflow can stop running even though it is still enabled and manual or workflow_dispatch runs still work.

This can happen when the workflow's associated actor account is suspended, deleted, or deprovisioned. To restart it, a user with write access to the repository can commit a change to the cron schedule. See Événements qui déclenchent des flux de travail.

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 Syntaxe de flux de travail pour GitHub Actions.

For path filtering, evaluating diffs is limited to the first 3,000 files. If there are files changed that are not matched in the first 3,000 files returned by the filter, the workflow will not be run. For more information, see Syntaxe de flux de travail pour GitHub Actions.

Troubleshoot workflow execution

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

Debugging job conditions

If a job was skipped unexpectedly, or ran when you expected it to be skipped, you can view the expression evaluation to understand why:

Click on the job in the workflow run.
Download the log archive from the job's menu.
Open the JOB-NAME/system.txt file.
Look for the Evaluating, Expanded, and Result lines.

The Expanded line shows the actual runtime values that were substituted into your if condition, making it clear why the expression evaluated to true or false.

For more information, see Affichage des journaux d’expressions de conditions des tâches.

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 Points de terminaison d'API REST pour l'exécution des workflows.

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 Utilisation de conditions pour contrôler l’exécution des travaux and Annulation d’une exécution de workflow.

If a run remains queued or in progress after cancellation attempts, it may be stuck in an abnormal state rather than continuing because of always(). Signs include no jobs being created, the UI displaying "Failed to cancel workflow", or the cancel or force-cancel REST API endpoints returning HTTP 500 or 409.

Self-service cancellation, including force cancellation, may not clear a stuck or out-of-sync workflow run or check suite. If your repository uses concurrency, the stuck run can continue blocking later runs in the same concurrency group. In this situation, contact us through the GitHub Support portal for help clearing the run.

Troubleshooting runners

Defining runner labels

GitHub-hosted runners leverage preset labels maintained through the actions/runner-images repository.

We recommend using unique label names for larger and self-hosted runners. If a label matches to any of the existing preset labels, there can be runner assignment issues where there is no guarantee on which matching runner option the job will run on.

Self-hosted runners

If you use self-hosted runners, you can view their activity and diagnose common issues.

For more information, see Surveillance des exécuteurs auto-hébergés et résolution des problèmes.

Runner IP addresses flagged by security scanners

GitHub-hosted runners use dynamically assigned IP addresses from shared infrastructure. These IP addresses are published via the Meta API (for example, the actions and actions_macos keys). For more information, see Points de terminaison d’API REST pour les métadonnées.

Third-party threat intelligence services, IP reputation scanners, or firewall vendors may flag these IP addresses as "malicious" or "suspicious." Because the underlying infrastructure is shared, activity from other users of the same infrastructure can influence the reputation scores assigned to these addresses.

GitHub does not control third-party IP reputation lists and cannot comment on their accuracy or update frequency. To verify whether an IP address belongs to GitHub-hosted runners, check the IP ranges returned by the Meta API.

If you have a security concern about a Microsoft-owned IP address, report it to the Microsoft Security Response Center (MSRC).

Networking troubleshooting suggestions

Our support is limited for network issues that involve:

Your networks
External networks
Third-party systems
General internet connectivity

To view GitHub's realtime platform status, check GitHub Status.

For other network-related issues, review your organization's network settings and verify the status of any third-party services you're accessing. If problems persist, consider reaching out to your network administrators for further assistance.

If you're unsure about the issue, contact GitHub Support. For details on how to contact support, see Contacter le support GitHub.

DNS

Issues may occur from Domain Name System (DNS) configuration, resolution, or resolver problems. We recommend you review available logs, vendor documentation, or consult with your administrators for additional assistance.

Firewalls

Activities may become blocked by firewalls. If this occurs, you may want to review available logs, vendor documentation, or consult with your administrators for additional assistance.

Proxies

Activities could fail when using a proxy for communications. It's good practice to review available logs, vendor documentation, or consult with your administrators for additional assistance.

Refer to Utilisation de serveurs proxy avec un exécuteur for information about configuring the runner application to utilize a proxy.

Subnets

It is possible to encounter issues with subnets in use or overlaps with an existing network, such as within virtual cloud provider or Docker networks. In such cases, we recommend you review your network topology and subnets in use.

Certificates

Issues may occur from self-signed or custom certificate chains and certificate stores. You can check that a certificate in use has not expired and is currently trusted. Certificates may be inspected with curl or similar tools. You can also review available logs, vendor documentation, or consult with your administrators for additional assistance.

IP lists

IP allow or deny lists may disrupt expected communications. If there is a problem, you should review available logs, vendor documentation, or consult with your administrators for additional assistance.

For information on GitHub's IP addresses, such as those used by GitHub-hosted runners, see À propos des adresses IP de GitHub.

Static IP addresses are available for use with GitHub-hosted larger runners. See Gestion des exécuteurs de plus grande taille for more information.

Operating systems and software applications

In addition to firewalls or proxies, customizations performed to GitHub-hosted runners, such as installing additional software packages, may result in communication disruptions. For information about available customization options, see Personnalisation des runners hébergés par GitHub.

For self-hosted runners, learn more about necessary endpoints in Documentation de référence relative aux runners auto-hébergés.
For help configuring WireGuard, see Utilisation de WireGuard pour créer un réseau de superposition.
For details about configuring OpenID Connect (OIDC), see Utilisation d’une passerelle API avec OIDC.

Azure private networking for GitHub-hosted runners

Issues may arise from the use of GitHub-hosted runners within your configured Azure Virtual Networks (VNETs) settings.

For troubleshooting advice, see Résolution des problèmes de configurations de réseau privé Azure pour les exécuteurs GitHub hébergés dans votre organisation or Dépannage des configurations de réseau privé Azure pour les runners hébergés par GitHub dans votre entreprise in the GitHub Enterprise Cloud docs.