# Error: The self-hosted runner registration token has expired. Please generate a new token and re-register the runner.

- **ID:** `policy/github-actions-self-hosted-runner-token-expired`
- **Domain:** policy
- **Category:** auth_error
- **Verification:** ai_generated
- **Fix Rate:** 95%

## Root Cause

GitHub self-hosted runner registration tokens have a configurable expiration (default 1 hour) and if the runner registration process is delayed or the token is stored and reused after expiration, registration fails.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| GitHub Actions Runner v2.311.0 | active | — | — |
| GitHub Actions Runner v2.312.0 | active | — | — |
| GitHub Actions Runner v2.313.0 | active | — | — |

## Workarounds

1. **Generate a new registration token from GitHub repository settings and re-register the runner.
Example:
  # On GitHub: Settings > Actions > Runners > New self-hosted runner > Copy token
  # On runner machine:
  ./config.sh remove --token OLD_TOKEN
  ./config.sh --url https://github.com/owner/repo --token NEW_TOKEN
  ./run.sh** (95% success)
   ```
   Generate a new registration token from GitHub repository settings and re-register the runner.
Example:
  # On GitHub: Settings > Actions > Runners > New self-hosted runner > Copy token
  # On runner machine:
  ./config.sh remove --token OLD_TOKEN
  ./config.sh --url https://github.com/owner/repo --token NEW_TOKEN
  ./run.sh
   ```
2. **Automate token generation using GitHub API in a script to avoid manual steps.
Example:
  # Get token using GitHub API
  TOKEN=$(curl -s -X POST -H "Authorization: token $GITHUB_PAT" \
    https://api.github.com/repos/owner/repo/actions/runners/registration-token | jq -r '.token')
  ./config.sh --url https://github.com/owner/repo --token $TOKEN** (90% success)
   ```
   Automate token generation using GitHub API in a script to avoid manual steps.
Example:
  # Get token using GitHub API
  TOKEN=$(curl -s -X POST -H "Authorization: token $GITHUB_PAT" \
    https://api.github.com/repos/owner/repo/actions/runners/registration-token | jq -r '.token')
  ./config.sh --url https://github.com/owner/repo --token $TOKEN
   ```
3. **Use a service like Terraform or Ansible to manage runner registration, ensuring tokens are generated fresh each time.
Example (Terraform):
  resource "github_actions_runner_registration_token" "this" {
    repository = "owner/repo"
  }
  # Then use the token in a provisioner** (85% success)
   ```
   Use a service like Terraform or Ansible to manage runner registration, ensuring tokens are generated fresh each time.
Example (Terraform):
  resource "github_actions_runner_registration_token" "this" {
    repository = "owner/repo"
  }
  # Then use the token in a provisioner
   ```

## Dead Ends

- **Restarting the runner service** — Restarting the runner service does not refresh the expired token; the token is only valid for initial registration, not for ongoing operations. (90% fail)
- **Editing .runner file to extend token expiration** — Modifying the .runner file to extend the expiration date manually will not work because the token is validated server-side by GitHub. (95% fail)
- **Deleting and re-adding with same token** — Deleting the runner from GitHub and re-adding it with the same expired token will still fail; a new token must be generated. (85% fail)