documentation.yml and compat-helper.yml read DOCUMENTER_KEY without declaring it

Open
  • Is something wrong?
#100 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
35/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Active
Tech stack
github-actions
Domain
ci-cd, devops

Research direction

Start in the reusable workflows .github/workflows/documentation.yml and .github/workflows/compat-helper.yml, where secrets.DOCUMENTER_KEY is read without a workflow_call.secrets declaration, then check docs/conventions/secrets.md for the documented behaviour. The issue offers three options, so a maintainer must choose one before a patch can be written; option 1 (remove the dead references) is the smallest. Done means the workflows and the secrets doc describe the same behaviour and no caller relies on an undeclared secret.

Written by the indexing model from the issue text.

Description

documentation.yml and compat-helper.yml read secrets.DOCUMENTER_KEY:

  • documentation.yml: DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} in both build and build-gpu
  • compat-helper.yml: COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}

Neither declares it under workflow_call.secrets. A reusable workflow only sees the secrets its caller passes, or all of them with secrets: inherit. No caller does either: on 2026-10-16 none of the Documentation.yml and CompatHelper.yml of CTBase, CTModels, CTParser, CTFlows, CTDirect, CTSolvers, OptimalControl, CTLie, OptimalControlProblems, CTDiffFlow, CTBenchmarks or CTAppTemplate mentions DOCUMENTER_KEY or secrets: inherit. The key is therefore always empty there.

Effect today

  • Documentation: Documenter falls back to GITHUB_TOKEN (HTTPS), and deployment works. Nothing is broken.
  • CompatHelper: COMPATHELPER_PRIV is empty, so CompatHelper pushes with GITHUB_TOKEN. Pushes and PRs made with GITHUB_TOKEN trigger no workflow. Since CI is label-gated, a human adding the label still starts it, so the impact is small. But it is not what the workflow says it does.

Options

  1. Keep the behaviour, remove the dead references. Drop DOCUMENTER_KEY and COMPATHELPER_PRIV from both workflows and say that deployment uses GITHUB_TOKEN. One PR in CTActions, nothing in the packages.
  2. Make the key work. Declare DOCUMENTER_KEY (optional) under workflow_call.secrets in both workflows, and pass it from every caller (secrets: DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}). One PR in CTActions, then one per package, or a change in the template plus a sweep.
  3. CompatHelper through the organization's GitHub App (control-toolbox-bot, see docs/conventions/github-app.md once CTActions#99 is merged): its PRs would run CI like the prune's. That needs the App's secrets to be visible to every package and installed on all of them, which is a broader decision.

Spotted while rewriting the docs (CTActions#99, docs/conventions/secrets.md, which documents the current behaviour).

Dominant language
Julia
Stars
1
Forks
0
Avg merge
1h 39m
Merged PRs (30d)
45

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from control-toolbox/CTActions

All issues in control-toolbox/CTActions

Similar issues

More Julia issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.