GitHub tracker: support renewable GitHub App installation tokens via token file

[blakedehaas]

Summary

While deploying Symphony as the orchestration layer for the autonomous software factory behind Simulated Singularity, I encountered a credential-lifecycle limitation in the GitHub Issues adapter. The deployment is reproducible in the open-source repository: https://github.com/blakedehaas/simulated-singularity

Symphony currently supports tracker.provider.token / GITHUB_TOKEN, but long-running Symphony processes cannot transparently rotate that credential when using short-lived GitHub App installation tokens.

I propose adding a tracker.provider.token_file option that is reread on each GitHub API request. A controller-side credential broker could then atomically replace the file with a newly minted installation token without restarting Symphony and without exposing the GitHub App private key to Codex workers.

Context

The software-factory architecture uses Symphony and Codex with strong separation of responsibilities:

GitHub Issue
    ↓
Symphony controller
    ↓
isolated issue workspace
    ↓
Codex app-server worker
    ↓
dedicated agent branch
    ↓
commit + validation
    ↓
pull request → agent integration branch

For GitHub access, the controller uses a dedicated repository-scoped GitHub App rather than a personal access token.

The App is responsible for operations such as:

• polling GitHub Issues for work,
• updating issue metadata,
• pushing autonomous agent branches,
• opening pull requests,
• and posting handoff information.

The design deliberately keeps the GitHub App private key outside Codex worker environments. Workers should only operate with tightly scoped permissions and should never require access to the App private key.

That architecture exposed the token-rotation problem described here.

Motivation

The deployment uses:

• GitHub Issues as the Symphony tracker,
• a repository-scoped GitHub App rather than a long-lived PAT,
• short-lived GitHub App installation access tokens,
• Codex workers that must never receive the App private key,
• long-running Symphony/controller processes,
• and isolated per-issue workspaces.

GitHub App installation tokens are intentionally short-lived.

The current static-token model therefore creates an operational mismatch: an installation token can expire while Symphony is still running.

Restarting Symphony periodically solely to rotate that credential is undesirable because it may disrupt orchestration state or long-running agent activity.

Passing the GitHub App private key into the Symphony/Codex worker environment would solve the refresh problem in the wrong place and weaken the security boundary.

A token-file abstraction allows the trust boundary to remain:

GitHub App private key
        |
        v
controller-side credential broker
        |
        v
short-lived installation token
        |
        v
/runtime/github-token
        |
        v
Symphony GitHub adapter

The credential broker can rotate /runtime/github-token atomically.

Symphony only receives the current short-lived credential.

Codex workers never need access to the App private key.

Proposed configuration

tracker:
  kind: github
  provider:
    repo: owner/repo
    token_file: /runtime/github-token

Environment-variable indirection could also be supported:

tracker:
  kind: github
  provider:
    repo: owner/repo
    token_file: $GITHUB_TOKEN_FILE

Existing token / GITHUB_TOKEN behavior should remain unchanged for backward compatibility.

Proposed behavior

For each GitHub API request:

1. Resolve token_file when configured.
2. Read and trim the current file contents.
3. Use that value as the request token.
4. If no token file is configured, preserve the existing token / GITHUB_TOKEN behavior.
5. If a configured token file cannot yield a usable token, return the existing missing-token error or an appropriately specific token-file error.

Reading the file per request is intentional: an external credential broker can rotate the token atomically while Symphony remains alive.

Because scheduler polling and the injected github_api tool both pass through the GitHub client, both paths can inherit token rotation without changes to worker behavior.

Minimal implementation

In elixir/lib/symphony_elixir/github/client.ex:

defp resolve_token(token_setting, token_file_setting, token_fallback, token_file_fallback) do
  case resolve_setting(token_file_setting, token_file_fallback) do
    nil ->
      resolve_setting(token_setting, token_fallback)

    token_file ->
      case File.read(token_file) do
        {:ok, token} -> normalize_string(token)
        {:error, _reason} -> nil
      end
  end
end

Then resolve the GitHub credential using:

token =
  resolve_token(
    provider["token"],
    provider["token_file"],
    System.get_env("GITHUB_TOKEN"),
    System.get_env("GITHUB_TOKEN_FILE")
  )

secret_environment_names/1 can also include GITHUB_TOKEN_FILE and any configured $VAR reference for token_file, preserving Symphony's existing credential-isolation behavior for Codex children.

Regression test

A focused test can prove that the value is actually reread rather than cached:

test "client rereads token_file for each GitHub request" do
  token_file =
    Path.join(
      System.tmp_dir!(),
      "symphony-github-token-#{System.unique_integer([:positive])}"
    )

  File.write!(token_file, "token-one\n")
  on_exit(fn -> File.rm(token_file) end)

  tracker_settings = %{
    kind: "github",
    provider: %{
      "repo" => "octo/repo",
      "token_file" => token_file
    },
    active_states: ["open"],
    terminal_states: ["closed"]
  }

  request_fun = fn "GET", "/repos/octo/repo/issues", _params, nil, settings ->
    send(self(), {:github_token, settings.token})
    {:ok, %{status: 200, body: []}}
  end

  assert {:ok, []} =
           Client.fetch_issues_by_states_for_test(
             ["open"],
             tracker_settings,
             request_fun
           )

  assert_receive {:github_token, "token-one"}

  File.write!(token_file, "token-two\n")

  assert {:ok, []} =
           Client.fetch_issues_by_states_for_test(
             ["open"],
             tracker_settings,
             request_fun
           )

  assert_receive {:github_token, "token-two"}
end

Security and operational benefits

This would:

• make short-lived GitHub App installation credentials practical for long-running Symphony deployments;
• preserve a clean separation between controller credentials and autonomous Codex workers;
• keep GitHub App private keys outside worker environments;
• avoid long-lived PATs;
• avoid embedding credentials in repo-owned WORKFLOW.md;
• avoid restarting Symphony solely for credential renewal;
• preserve Symphony's existing host-side tracker-auth architecture;
• support stronger least-privilege software-factory deployments;
• require only a small localized extension to the existing GitHub adapter.

Real-world reproduction

The complete autonomous workflow has been exercised successfully:

GitHub Issue
    ↓
Symphony
    ↓
isolated workspace
    ↓
Codex app-server
    ↓
agent branch
    ↓
implementation
    ↓
validation
    ↓
commit
    ↓
push
    ↓
pull request → integration branch
    ↓
issue handoff

An end-to-end smoke test successfully created an issue-specific branch, committed a test artifact, validated it, pushed the branch, opened a pull request against the integration branch, posted a handoff comment, and removed its dispatch label when complete.

The remaining infrastructure problem is credential lifecycle: GitHub App installation tokens expire much sooner than Symphony itself is expected to run.

I currently have the token_file approach implemented as a narrow downstream compatibility patch against Symphony v0.0.2, along with a token-rotation regression test. The preference is to remove that downstream patch once Symphony provides an upstream-supported mechanism.

If maintainers prefer a different abstraction—for example a credential-provider callback, executable credential helper, first-class GitHub App configuration, or another renewable-secret interface—the underlying requirement is simply:

Allow the GitHub adapter to obtain a fresh short-lived credential during a long-running Symphony process without requiring an orchestrator restart or exposing the GitHub App private key to Codex workers.