local-release-test

name	local-release-test
description	Use the repository-local GitHub Actions release workflow to publish prerelease test builds from development branches without touching the official InternScience/InternAgents release repository.

Local Release Test

Use this skill when a developer asks to create, run, monitor, or explain the repository-local release testing workflow for InternAgentS desktop builds.

The goal is to let different developers publish test releases from different branches in qzzqzzb/InternAgents without overwriting official releases or each other's test builds.

Release Model

• Official releases are triggered by pushing tags like v0.1.5 to InternScience/InternAgents.
• Official releases run and publish in InternScience/InternAgents using that repository's built-in GITHUB_TOKEN.
• Local test releases are triggered manually with workflow_dispatch.
• Local test releases publish to the current repository, normally qzzqzzb/InternAgents.
• Local test releases require secrets.INTERNAGENTS_LOCAL_RELEASE_TOKEN.
• Local test releases are marked as GitHub prereleases, so they do not replace the repository's latest stable release.
• Package-only builds are triggered manually with workflow_dispatch in InternScience/InternAgents.
• Package-only builds run in InternScience/InternAgents and upload workflow artifacts only; they do not create or update GitHub Releases.

The workflow generates test tags automatically:

v<base_version>-test.<safe_branch_name>.<utc_timestamp>

Example:

v0.1.5-test.zhf-local-release-for-test.20260603.192500

The timestamp is UTC in yyyyMMdd.HHmmss format. Branch separators and unsafe characters are normalized to hyphens.

The workflow intentionally does not define a custom GitHub Actions run-name; GitHub uses the default workflow run display. The final GitHub Release tag and title include the branch timestamp and are the source of truth for test release identity.

Before Running

1. Confirm the developer branch has been pushed to GitHub.
2. Confirm .github/workflows/release.yml on the default branch includes workflow_dispatch. If this workflow support is still only in a PR branch, merge that support first before relying on manual dispatch.
3. Confirm the branch includes the code that should be packaged.
4. Choose a base_version, usually the next version being tested, such as 0.1.5.
5. Confirm repository secret INTERNAGENTS_LOCAL_RELEASE_TOKEN exists and can write Contents to qzzqzzb/InternAgents.

Trigger From GitHub UI

1. Open qzzqzzb/InternAgents on GitHub.
2. Go to Actions.
3. Select the Release workflow.
4. Click Run workflow.
5. Select the development branch to package.
6. Set base_version.
7. Optionally set release_notes.
8. Start the workflow.

Trigger With GitHub CLI

Use gh when it is available and authenticated:

gh workflow run release.yml `
  --repo qzzqzzb/InternAgents `
  --ref <branch-name> `
  -f base_version=0.1.5 `
  -f release_notes="Testing <short summary>"

Then monitor the run:

gh run list --repo qzzqzzb/InternAgents --workflow release.yml --limit 5
gh run watch --repo qzzqzzb/InternAgents <run-id>

If gh is not installed, use the GitHub connector or GitHub web UI to inspect workflow runs.

Expected Artifacts

The workflow should publish a prerelease in qzzqzzb/InternAgents with:

• macOS Apple Silicon DMG
• macOS Intel DMG
• Windows x64 NSIS installer
• remote backend CLI tarball: internagents-backend-cli.tar.gz

The release notes include:

• generated test release tag
• desktop version used for packaging
• source branch and commit
• exact INTERNAGENTS_UPDATE_API_URL for testing app updates against that prerelease
• exact INTERNAGENTS_REMOTE_BACKEND_UPDATE_API_URL for testing remote backend CLI release sync against that prerelease

Official Package-Only Builds

Use the package-only workflow when the developer wants InternScience/InternAgents to run the build but does not want to publish a GitHub Release.

Trigger the workflow manually and point it at the source ref to package:

gh workflow run package.yml `
  --repo InternScience/InternAgents `
  -f source_repository=qzzqzzb/InternAgents `
  -f source_ref=main `
  -f desktop_version=0.1.5

Then monitor the run:

gh run list --repo InternScience/InternAgents --workflow package.yml --limit 5
gh run watch --repo InternScience/InternAgents <run-id>

Expected workflow artifacts:

• macOS Apple Silicon DMG
• macOS Intel DMG
• Windows x64 NSIS installer
• remote backend CLI tarball: internagents-backend-cli.tar.gz

The workflow does not create or edit a GitHub Release. Pushing a package tag is not part of this flow; for a private source repository, configure INTERNAGENTS_SOURCE_TOKEN in InternScience/InternAgents with read access to that source repository. This workflow does not update the InternScience/InternAgents main branch.

Testing App Updates Against A Test Release

Because local test releases are prereleases, clients should use the exact release API URL from the release notes rather than relying on /releases/latest.

Set this in .env when testing update checks locally:

INTERNAGENTS_UPDATE_API_URL=https://api.github.com/repos/qzzqzzb/InternAgents/releases/tags/<generated-test-tag>
INTERNAGENTS_REMOTE_BACKEND_UPDATE_API_URL=https://api.github.com/repos/qzzqzzb/InternAgents/releases/tags/<generated-test-tag>

For example:

INTERNAGENTS_UPDATE_API_URL=https://api.github.com/repos/qzzqzzb/InternAgents/releases/tags/v0.1.5-test.zhf-local-release-for-test.20260603.192500
INTERNAGENTS_REMOTE_BACKEND_UPDATE_API_URL=https://api.github.com/repos/qzzqzzb/InternAgents/releases/tags/v0.1.5-test.zhf-local-release-for-test.20260603.192500

Restart the app/backend after changing .env so the update endpoint reads the new value.

The same generated release API URL can be used for desktop update checks and remote backend release sync for the selected test build.

Safety Rules

• Do not push or overwrite official v*.*.* tags for test-only builds.
• Do not fall back to GITHUB_TOKEN for local release publishing; the workflow expects INTERNAGENTS_LOCAL_RELEASE_TOKEN.
• Keep local test releases as prereleases unless the developer explicitly asks for a stable release flow change.
• Prefer creating a fresh test release per run; branch-and-timestamp tags are designed to make that cheap and collision-free.
• Do not reintroduce a custom workflow run-name unless it has been validated with GitHub Actions expression rules.

Troubleshooting

• If the workflow is not shown in the GitHub UI, check that the workflow file with workflow_dispatch has been merged to the default branch.
• If the run fails before build jobs start, inspect the Prepare release metadata job first.
• If release publishing fails with permission errors during a test release, confirm INTERNAGENTS_LOCAL_RELEASE_TOKEN is set as an Actions secret, is scoped to qzzqzzb/InternAgents, and has repository Contents read/write permission. Also confirm the release job has contents: write.
• If the app does not see a test release, use INTERNAGENTS_UPDATE_API_URL with the exact generated tag URL.
• If an official tag run tries to publish to the development repository, stop and inspect metadata outputs before rerunning.