docs: stop pointing at a login plugin that does not exist - #20
Open
NickJosevski wants to merge 1 commit into
Open
docs: stop pointing at a login plugin that does not exist#20NickJosevski wants to merge 1 commit into
NickJosevski wants to merge 1 commit into
Conversation
v0.2.0 shipped with an Authentication section recommending OctopusDeploy/octopus-login-buildkite-plugin, which 404s. Two of the plugin's own error messages sent people there too, so a misconfigured step told the user to go and find something unpublished. Replaces it with what actually works today: the api_key path, and a worked OpenID Connect recipe doing the RFC 8693 exchange in a step, linked to the Octopus "other issuers" documentation. Calls out that Buildkite's subject claim pins the commit SHA, so `commit:*` is effectively required in the OIDC identity's subject - without it the identity only authorises the build it was created from. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
NickJosevski
enabled auto-merge (rebase)
August 31, 2026 01:38
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
1 participant
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.
The problem
v0.2.0 is public, and its Authentication section recommends
OctopusDeploy/octopus-login-buildkite-plugin— which 404s. Anyone following the recommended path from the released docs hits a dead end immediately.It's worse than a broken link: two of the plugin's own error messages sent people there as well, so a misconfigured step told the user to go find something that was never published.
The fix
Document what works today instead of a plugin that doesn't exist:
server+api_key, as the examples already show.OCTOPUS_ACCESS_TOKEN, linked to the Octopus other-issuers docs. This is the flow verified end to end on a Buildkite hosted agent, so it's known to work rather than inferred.Error messages and
plugin.ymldescriptions now describe the env vars and properties rather than the missing plugin.One thing worth keeping in the docs
Buildkite's subject claim pins the commit SHA:
so
commit:*is effectively required in the OIDC identity's subject. Without it the identity authorises exactly one build and then silently never matches again — a failure that's very hard to diagnose from the error Octopus returns. The README now says so explicitly.When the login plugin ships
This section should go back to recommending it. The manual recipe stays useful as the "what the plugin does for you" explanation.
Verification
16 tests, linter (6 examples valid, version refs up to date at v0.2.0), shellcheck all pass.
🤖 Generated with Claude Code