Troubleshooting GitHub Actions for your enterprise

Checking the health of GitHub Actions

You can check the health of GitHub Actions on your GitHub Enterprise Server instance with the ghe-actions-check command-line utility. For more information, see Command-line utilities and Accessing the administrative shell (SSH).

Configuring self-hosted runners when using a self-signed certificate for GitHub Enterprise Server

We strongly recommend that you configure TLS on GitHub Enterprise Server with a certificate signed by a trusted authority. Although a self-signed certificate can work, extra configuration is required for your self-hosted runners, and it is not recommended for production environments. For more information, see Configuring TLS.

Installing the certificate on the runner machine

For a self-hosted runner to connect to a GitHub Enterprise Server using a self-signed certificate, you must install the certificate on the runner machine so that the connection is security hardened.

For the steps required to install a certificate, refer to the documentation for your runner's operating system.

Configuring Node.JS to use the certificate

Most actions are written in JavaScript and run using Node.js, which does not use the operating system certificate store. For the self-hosted runner application to use the certificate, you must set the NODE_EXTRA_CA_CERTS environment variable on the runner machine.

You can set the environment variable as a system environment variable, or declare it in a file called .env in the self-hosted runner application directory (that is, the directory into which you downloaded and unpacked the runner software).

For example:

NODE_EXTRA_CA_CERTS=/usr/share/ca-certificates/extra/mycertfile.crt

Environment variables are read when the self-hosted runner application starts, so you must set the environment variable before configuring or starting the self-hosted runner application. If your certificate configuration changes, you must restart the self-hosted runner application.

Configuring Docker containers to use the certificate

If you use Docker container actions or service containers in your workflows, you might also need to install the certificate in your Docker image in addition to setting the above environment variable.

Configuring HTTP proxy settings for GitHub Actions

If you have an HTTP Proxy Server configured on GitHub:

• You must add .localhost, 127.0.0.1, and ::1 to the HTTP Proxy Exclusion list (in this order).
• If your external storage location is not routable, then you must also add your external storage URL to the exclusion list.

For more information on changing your proxy settings, see Configuring an outbound web proxy server.

If these settings aren't correctly configured, you might receive errors like Resource unexpectedly moved to https://IP-ADDRESS when setting or changing your GitHub Actions configuration.

Runners not connecting to GitHub Enterprise Server with a new hostname

If you deploy GitHub Enterprise Server in your environment with a new hostname and the old hostname no longer resolves to your instance, self-hosted runners will be unable to connect to the old hostname, and will not execute any jobs.

You will need to update the configuration of your self-hosted runners to use the new hostname for your GitHub Enterprise Server instance. Each self-hosted runner will require one of the following procedures:

• In the self-hosted runner application directory, edit the .runner and .credentials files to replace all mentions of the old hostname with the new hostname, then restart the self-hosted runner application.
• Remove the runner from GitHub Enterprise Server using the UI, and re-add it. For more information, see Removing self-hosted runners and Adding self-hosted runners.

Troubleshooting failures when Dependabot triggers existing workflows

After you set up Dependabot updates for your GitHub Enterprise Server instance, you may see failures when existing workflows are triggered by Dependabot events.

By default, GitHub Actions workflow runs that are triggered by Dependabot from push, pull_request, pull_request_review, or pull_request_review_comment events are treated as if they were opened from a repository fork. Unlike workflows triggered by other actors, this means they receive a read-only GITHUB_TOKEN and do not have access to any secrets that are normally available. This will cause any workflows that attempt to write to the repository to fail when they are triggered by Dependabot.

There are three ways to resolve this problem:

1. You can update your workflows so that they are no longer triggered by Dependabot using an expression like: if: github.actor != 'dependabot[bot]'. For more information, see Evaluate expressions in workflows and actions.
2. You can modify your workflows to use a two-step process that includes pull_request_target which does not have these limitations. For more information, see Troubleshooting Dependabot on GitHub Actions.
3. You can provide workflows triggered by Dependabot access to secrets and allow the permissions term to increase the default scope of the GITHUB_TOKEN. For more information, see Providing workflows triggered by Dependabot access to secrets and increased permissions below.

Providing workflows triggered by Dependabot access to secrets and increased permissions

1. Log in to the administrative shell using SSH. For more information, see Accessing the administrative shell (SSH).

2. To remove the limitations on workflows triggered by Dependabot on your GitHub Enterprise Server instance, use the following command.

   ghe-config app.actions.disable-dependabot-enforcement true
   

3. Apply the configuration.

   ghe-config-apply
   

4. Return to GitHub Enterprise Server.

Troubleshooting bundled actions in GitHub Actions

If you receive the following error when installing GitHub Actions in GitHub Enterprise Server, you can resolve the problem by installing the official bundled actions and workflow templates.

A part of the Actions setup had problems and needs an administrator to resolve.

To install the official bundled actions and workflow templates within a designated organization in GitHub Enterprise Server, follow this procedure.

1. Identify an organization that will store the official bundled actions and workflow templates. You can create a new organization or reuse an existing one.

   • To create a new organization, see Creating a new organization from scratch.
   • For assistance with choosing a name for this organization, see Getting started with GitHub Actions for GitHub Enterprise Server.

2. Log in to the administrative shell using SSH. For more information, see Accessing the administrative shell (SSH).

3. To designate your organization as the location to store the bundled actions, use the ghe-config command, replacing ORGANIZATION with the name of your organization.

   ghe-config app.actions.actions-org ORGANIZATION
   

   and:

   ghe-config app.actions.github-org ORGANIZATION
   

4. To add the bundled actions to your organization, unset the SHA.

   ghe-config --unset 'app.actions.actions-repos-sha1sum'
   

5. Apply the configuration.

   ghe-config-apply
   

After you've completed these steps, you can resume configuring GitHub Actions at Getting started with GitHub Actions for GitHub Enterprise Server.