docs(dns): scoped secret-set + IaC DNS provider matrix#741
Merged
Conversation
Per workflow#735 SPEC T19. docs/wfctl-secrets-scopes.md: - Scope table (repo/env/org) with URL prefix + PAT scope + visibility flags. - Repo default examples (value/from-file/piped/masked-TTY). - Env scope reads repo from app.yaml. - Org scope bypass-app.yaml + visibility flag (all/selected/private). - Plugin-driven setup walkthrough. - PAT scope cheat sheet (repo / repo+workflow / admin:org). - Troubleshooting (403/422/encryption errors). docs/iac-dns-providers.md: - Provider matrix: DigitalOcean (verified) / Namecheap / Hover. - Auth + CIDR / bulk-op caveats per provider. - Common config shape with all record types (A/AAAA/CNAME/MX/TXT). - Namecheap single-IP allowlist gotcha (NAT/bastion workaround). - Hover browser-flow auth + TOTP + failure modes (CAPTCHA, HTML regex breakage). - infra.dyndns config example with multi-source quorum. - Cross-link to wfctl-secrets-scopes.md + the DNS-providers plan. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds two new operator-facing documentation pages intended to (1) explain wfctl GitHub secret scoping and (2) provide an IaC DNS provider capability/auth matrix for infra.dns (per workflow#735 SPEC T19).
Changes:
- Add
docs/wfctl-secrets-scopes.mddescribing repo/env/org GitHub secret destinations and required token scopes. - Add
docs/iac-dns-providers.mddescribing DNS provider plugins, config shape, and operational notes.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/wfctl-secrets-scopes.md | New doc describing GitHub secret scopes and intended wfctl secrets usage patterns. |
| docs/iac-dns-providers.md | New doc describing infra.dns providers, configuration examples, and operational guidance. |
Comments suppressed due to low confidence (7)
docs/wfctl-secrets-scopes.md:27
- This section claims piped stdin is honored for
wfctl secrets set, but the implementation only reads from--value,--from-file, an explicit injected reader (tests), or an interactive TTY prompt; non-TTY stdin currently errors. Either update the docs to match current behavior or update the command implementation to read from stdin when it’s not a TTY.
Pipes are honored:
```sh
echo -n "abc123" | wfctl secrets set MY_TOKEN
**docs/wfctl-secrets-scopes.md:72**
* The org-scope example for `--visibility selected` implies repo IDs are populated “via a follow-up” and that the CLI will accept them in a future flag. In the current GitHub provider, visibility=selected requires `selected_repository_ids` at provider creation time; `wfctl secrets set --scope org` currently passes `nil` for selected repo IDs, so `--visibility selected` would fail. Please either document that `selected` isn’t supported by `wfctl` yet (and should not be used), or adjust the guidance/examples accordingly.
Only the listed repo IDs can pull. (selected_repository_ids
are populated programmatically via a follow-up; CLI accepts
them in a future flag.)
wfctl secrets set CI_SECRET
--scope org --org GoCodeAlone
--visibility selected
--value "..."
**docs/wfctl-secrets-scopes.md:92**
* This “Plugin-driven setup” section describes `wfctl secrets setup --plugin ...` reading `data/plugins/<plugin>/plugin.json` and iterating `required_secrets[]`, but the current `wfctl secrets setup` implementation only supports `--env` and reads `secrets.entries` from the workflow config. If plugin-driven setup is not implemented in this repo yet, this section should be removed or moved to a future/plan doc to avoid sending operators to a non-existent command/manifest format.
Plugin-driven setup
If you're configuring a plugin that declares required_secrets[] in
its plugin.json (workflow-plugin-namecheap, workflow-plugin-hover,
etc.), use the interactive setup flow:
wfctl secrets setup --plugin workflow-plugin-hover \
--scope org --org GoCodeAlone --visibility allThis:
- Reads
data/plugins/workflow-plugin-hover/plugin.json. - Iterates
required_secrets[]. - Prompts for each (masked iff
sensitive: true). - Writes each to the chosen GH scope.
**docs/wfctl-secrets-scopes.md:115**
* The troubleshooting note says the setup flow “skips empty values,” but this doc’s earlier `secrets set` flow would attempt to write an empty value if the user just presses Enter in the masked prompt, which can trigger the GitHub 422 error. Consider rephrasing to distinguish between `wfctl secrets set` (single secret) vs `wfctl secrets setup` (bulk) behavior, and remove the “echo settings” suggestion if the input is masked (no terminal echo).
HTTP 422: secret value cannot be empty— the prompted value
was empty. The setup flow skips empty values; check terminal
echo settings.
**docs/iac-dns-providers.md:33**
* This example declares DNS under a top-level `resources:` key. `WorkflowConfig` expects infrastructure resources under `infrastructure.resources` (or, for infra.yaml examples elsewhere in this repo, infra resources are declared as `modules` with `type: infra.*`). As written, `resources:` would be ignored by config loading. Please adjust the YAML shape to match one supported by the engine/CLI.
resources:
- name:
type: infra.dns
config:
provider:
**docs/iac-dns-providers.md:120**
* This doc references an `infra.dyndns` module and describes its behavior/config, but there is no `infra.dyndns` module type in this repo at the moment. Please remove/flag this section as planned functionality (or link to the plugin/module that actually provides it) to avoid documenting a non-existent module.
Dynamic DNS
For dynamic IPs (home labs, mobile workstations), pair any DNS
provider with the infra.dyndns module:
- name: home-dns
type: infra.dyndns
config:
provider: namecheap # any iac.provider.* module name
domain: gocodealone.tech
record_name: home
poll_interval: 5m
detect_via: [icanhazip, ifconfig.me, ipify]
quorum: 2 # 2-of-3 must agree before update fires**docs/iac-dns-providers.md:145**
* The secret management section recommends `wfctl secrets setup --plugin ... --scope ...`, but the current `wfctl secrets setup` command only supports `--env` and reads secrets from config (no `--plugin`/`--scope` flags). Please update these commands to something that exists today, or clearly mark them as future/planned so operators don’t try to run unsupported flags.
Secret management
Each provider declares its required secrets in plugin.json's
required_secrets[]. To set them all at once:
wfctl secrets setup --plugin workflow-plugin-namecheap \
--scope org --org GoCodeAlone
wfctl secrets setup --plugin workflow-plugin-hover \
--scope env --env production</details>
Comment on lines
+3
to
+5
| `wfctl secrets set` and `wfctl secrets setup --plugin` both write to | ||
| one of three GitHub secret destinations. Each requires a different | ||
| PAT scope and exposes different visibility controls. |
Comment on lines
+19
to
+20
| type: iac.provider.<digitalocean|namecheap|hover> | ||
| config: |
⏱ Benchmark Results✅ No significant performance regressions detected. benchstat comparison (baseline → PR)
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Per workflow#735 SPEC T19. Two new operator docs.