ci: fix the startup failure on merge to main

[nadvolod]

The first run of Publish Kotlin Nexus track (the one PR #9's merge triggered) died as startup_failure with zero jobs and no readable log.

Why it failed at startup

A caller's permissions: block is the ceiling for every job in the called reusable workflow, and GitHub validates that ceiling when it loads the workflow, before any if: is evaluated.

The caller granted packages: read. _track-ci.yml's build-image job asks for packages: write. build-image never runs here (build_image: false), but a disabled job still counts toward the check, so the run was rejected before it could log why.

Raised the ceiling to packages: write, with a comment explaining why that belongs next to build_image: false so nobody narrows it back.

Why that alone was not enough

This repo has no INSTRUQT_TOKEN secret (checked both repo and org scope). Fixing the ceiling would have converted a startup failure into an auth failure on instruqt track push on every merge.

The push steps now run behind a token check that emits a ::warning:: naming the fix and skips. Publishing stays manual until someone adds the secret, and nothing here has to change when they do. The check is a step, not a job-level if, because the secrets context is not available in the latter.

Impact on the live track

None. The track is already published and instruqt track pull reports it up to date, so the skipped push would have been a no-op anyway.

Verification

• Both workflow files parse as YAML.
• Ceiling check against every job in _track-ci.yml: contents: read ok, packages: write ok.

Also documented both traps in INSTRUQT.md and the token requirement in README.md.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR addresses a GitHub Actions reusable-workflow startup failure on merges to main by aligning the caller workflow’s permissions ceiling with the called workflow’s job requirements, and adds documentation around the failure mode and token requirements for publishing an Instruqt track.

Changes:

• Raised caller workflow packages permission to write to satisfy the reusable workflow’s (even-disabled) build-image job permissions.
• Added an INSTRUQT_TOKEN presence check and conditional gating around the publish steps to avoid hard failures when the secret is missing.
• Documented both the permissions-ceiling trap and the missing-token behavior in README.md and INSTRUQT.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
README.md	Documents current “no-op” publish behavior without INSTRUQT_TOKEN and explains the reusable-workflow permissions ceiling pitfall.
INSTRUQT.md	Adds a troubleshooting section explaining startup failures from permissions ceilings and guidance for handling missing tokens.
.github/workflows/build-and-push-kotlin.yml	Raises packages permission ceiling to prevent workflow-load startup failures when calling the reusable workflow.
.github/workflows/_track-ci.yml	Adds token-check step and conditions publishing steps on token presence to avoid failing merges when secret is absent.

Suppressed comments (1)

.github/workflows/_track-ci.yml:120

• Validation is valuable signal even when publishing is intentionally disabled (no token). Since instruqt track validate does not require auth, consider running this step unconditionally and leaving only the push step conditional on has_token.

      - name: Validate track
        if: steps.auth.outputs.has_token == 'true'
        working-directory: ${{ inputs.track_dir }}/instruqt

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.