docs(executor): say where secrets.GITHUB_TOKEN comes from

It is github.token of the contexts the server sends: a token of its own,
scoped to the job, never the ermitejob_ job token, which must not reach the
sandbox. ermite does not send one yet (planned for CI-3).

commit: a0aa4178dd2d79815a2a937acb530b656c3362f2
author: brice · 9d ago · 2026-10-13 04:08 UTC
parent: e1ff0f2
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +15 -5

M internal/executor/contexts.go +15 -5


@@ -477,11 +477,21 @@ func (s State) Values(env ordered) map[string]expr.Value {
477	477		return m
478	478		}
479	479
480		-	// secrets is the secrets context. The job's token is in it as GITHUB_TOKEN
481		-	// (Variables.ToSecretsContext keeps every secret variable but the access token;
482		-	// GitHub's job message carries the token as a secret named GITHUB_TOKEN, recorded:
483		-	// ctx-inputs-vars, secrets.GITHUB_TOKEN == github.token). Without a token the
484		-	// context is empty.
	480	+	// secrets is the secrets context. Today it holds one entry, GITHUB_TOKEN, as
	481	+	// on GitHub (Variables.ToSecretsContext lists the secret variables but the
	482	+	// access token; GitHub's message carries the token as the secret GITHUB_TOKEN,
	483	+	// recorded: ctx-inputs-vars, secrets.GITHUB_TOKEN == github.token).
	484	+	//
	485	+	// Where the value comes from: the "token" key of the github context that the
	486	+	// server sends in Job.contexts, the same value as github.token. It must be a
	487	+	// token of its own, scoped to the job (the permissions "Set up job" prints) and
	488	+	// short lived. It must never be the "ermitejob_" job token: that one
	489	+	// authenticates the runner's calls to ermite, stays in the runner host process
	490	+	// and must not reach the sandbox (runner.proto, "Secrets and trust"). ermite
	491	+	// does not send a token yet (planned for CI-3, with the secrets of the
	492	+	// repository); until it does, github.token is empty, so is secrets, and
	493	+	// a test of secrets.GITHUB_TOKEN against the empty string is false. Without a
	494	+	// token nothing is masked.
485	495		func (s State) secrets() expr.Dictionary {
486	496		d := expr.NewDictionary()
487	497		if t := s.GitHub("token"); t != "" {

 	return m
 }
-// secrets is the secrets context. The job's token is in it as GITHUB_TOKEN
+// secrets is the secrets context. Today it holds one entry, GITHUB_TOKEN, as
-// (Variables.ToSecretsContext keeps every secret variable but the access token;
+// on GitHub (Variables.ToSecretsContext lists the secret variables but the
-// GitHub's job message carries the token as a secret named GITHUB_TOKEN, recorded:
+// access token; GitHub's message carries the token as the secret GITHUB_TOKEN,
-// ctx-inputs-vars, secrets.GITHUB_TOKEN == github.token). Without a token the
+// recorded: ctx-inputs-vars, secrets.GITHUB_TOKEN == github.token).
-// context is empty.
+//
+// Where the value comes from: the "token" key of the github context that the
+// server sends in Job.contexts, the same value as github.token. It must be a
+// token of its own, scoped to the job (the permissions "Set up job" prints) and
+// short lived. It must never be the "ermitejob_" job token: that one
+// authenticates the runner's calls to ermite, stays in the runner host process
+// and must not reach the sandbox (runner.proto, "Secrets and trust"). ermite
+// does not send a token yet (planned for CI-3, with the secrets of the
+// repository); until it does, github.token is empty, so is secrets, and
+// a test of secrets.GITHUB_TOKEN against the empty string is false. Without a
+// token nothing is masked.
 func (s *State) secrets() *expr.Dictionary {
 	d := expr.NewDictionary()
 	if t := s.GitHub("token"); t != "" {