The GitLab CI runner failed because its authentication token expired, meaning the runner can no longer prove its identity to the GitLab server.
One of the most common reasons for this is simply the token’s default expiration. GitLab CI runner tokens are set to expire after one year by default. If you’re using the default token for a runner registered more than a year ago, it will inevitably expire.
Diagnosis: To check the expiration date of your runner’s token, you can use the GitLab API. Make a GET request to https://your.gitlab.instance/api/v4/runners/<runner_id> (replace your.gitlab.instance with your GitLab URL and <runner_id> with the specific runner’s ID). The response will contain a token_expires_at field.
Fix: If the token has expired, you need to generate a new one. Navigate to your GitLab project or group’s CI/CD settings, find the Runners section, and click "Register a new runner." A new registration token will be generated. You then need to re-register your runner with this new token. On the runner machine, stop the runner service (sudo gitlab-runner stop), edit its configuration file (usually /etc/gitlab-runner/config.toml), update the token value with the new token, and then restart the service (sudo gitlab-runner start). This works because the runner’s config.toml stores the authentication token it uses to communicate with the GitLab API; updating this file provides the server with a valid, current credential.
Another frequent cause is manual revocation of the runner token. An administrator or project owner might have explicitly revoked the token from the GitLab UI, perhaps due to security concerns or a belief that the runner was no longer needed.
Diagnosis: In the GitLab UI, navigate to your project or group’s CI/CD settings, then to the Runners section. If the runner is listed and shows as "Disconnected" or has a warning icon, it’s worth checking its status. The API endpoint mentioned earlier (/api/v4/runners/<runner_id>) will also show a active status. If active is false, the token may have been revoked.
Fix: If the token was revoked, you’ll need to generate a new one and re-register the runner, just as described in the previous point. The process of re-registration with a new token effectively replaces the old, revoked credential with a new, valid one in the runner’s configuration.
Sometimes, the issue isn’t the token itself but the GitLab instance’s configuration regarding runner authentication. Specific GitLab configurations, especially in self-hosted instances, might enforce stricter token rotation policies or have specific settings that could lead to premature expiry or invalidation.
Diagnosis: Check your GitLab instance’s configuration files (e.g., gitlab.rb for Omnibus installations) for settings related to runner tokens, such as gitlab_rails['runner_token_expiration_days']. Also, review any custom CI/CD settings in the GitLab UI that might affect runner authentication.
Fix: If you find a restrictive policy, you can adjust it. For example, in gitlab.rb, you might set gitlab_rails['runner_token_expiration_days'] = 0 to disable token expiration entirely, or increase the value to a much longer period. After modifying gitlab.rb, run sudo gitlab-ctl reconfigure on your GitLab server. This reconfigures the GitLab application to use the new token expiration policy, allowing existing or re-registered runners to authenticate without immediate expiry.
It’s also possible that the runner’s config.toml file itself has been corrupted or is pointing to an incorrect GitLab instance URL, making the token appear invalid even if it’s not.
Diagnosis: Examine the runner’s configuration file, typically located at /etc/gitlab-runner/config.toml on Linux systems. Look for the [[runners]] section and verify the url parameter points to the correct GitLab instance and that the token value is present and appears correctly formatted.
Fix: Correct any typos in the url or token fields in config.toml. If the token is missing or malformed, obtain a new registration token from your GitLab instance and update the token field. After saving the changes, restart the runner service: sudo gitlab-runner restart. This ensures the runner uses the corrected configuration and a valid token to communicate with the intended GitLab server.
A less common but still relevant cause is a mismatch between the runner’s registered GitLab instance and the one it’s trying to authenticate with. This can happen if the runner’s configuration was accidentally updated to point to a different GitLab server, or if there’s a DNS issue preventing the runner from reaching the intended instance.
Diagnosis: Again, check the url parameter in the runner’s /etc/gitlab-runner/config.toml. Ensure it matches the exact URL of your GitLab server. You can also try to ping or curl the GitLab URL from the runner machine to verify network connectivity.
Fix: Update the url in config.toml to the correct GitLab instance URL. If network issues are suspected, troubleshoot DNS or firewall rules. After correcting the URL and ensuring connectivity, restart the runner: sudo gitlab-runner restart. This forces the runner to attempt authentication with the correct GitLab instance using its current token.
Finally, consider that the runner’s system clock might be significantly out of sync. If the runner’s time is drastically different from the GitLab server’s time, it can cause authentication issues, including token validation failures, as timestamps in communication are used for security checks.
Diagnosis: On the runner machine, check the system time using the date command. Compare it with the current time on your GitLab server or a reliable time source.
Fix: Synchronize the runner’s system clock with an NTP server. On most Linux systems, you can use sudo timedatectl set-ntp true to enable NTP synchronization. If NTP is already enabled but not working, you may need to configure a specific NTP server in /etc/systemd/timesyncd.conf and then restart the time synchronization service. Correcting the system clock ensures that all communication, including token validation, uses consistent timestamps, resolving potential authentication errors.
Once all these issues are resolved, the next error you’re likely to encounter is a "runner not found" error if the runner’s registration was lost due to an expired or revoked token, and it hasn’t been re-registered correctly.