GitHub Repositories

Connect a repository#

Linking happens per target, so a TypeScript and a Python SDK can live in separate repositories.

How syncing works#

Builds never commit straight to your default branch. The repository follows a three-branch flow that Scalar manages together with the generated workflows, all of which run on the default GITHUB_TOKEN — no extra token to provision.

• scalar-generated holds pristine generator output. Scalar pushes here; you never commit to it.
• scalar-next holds that output merged with your custom code. This is where you commit your own changes, directly or through pull requests, and where Scalar merges each regeneration.
• The default branch (main unless you configure otherwise) only ever receives released states. Scalar keeps a release pull request open from scalar-next against it, so the diff you review is the entire pending release. Merging that pull request is what releases and publishes the version.
• scalar-merge-conflict carries a regeneration that could not be merged cleanly; it arrives as a pull request for you to resolve.

Synced versions: the target lists each SDK version next to the pull request and commit that delivered it, so you can trace a published version back to its build.

[!NOTE] Linking only controls where generated code goes. Turn on Publish to <registry> on merge (or add a publish block to the target) to also push the package to its registry. See Publishing.

Promotion#

By default every successful build reaches production on its own: it pushes to scalar-generated, merges into scalar-next, and updates the release pull request. Set a target to promote manually and that last part waits for you.

A manual target still builds on every change, and its staging repository — a private playground that mirrors the latest build — is still updated. What waits is the push to the repository your team works in, until you click Promote to production.

Use it when generated output should be reviewed before it lands in your repository, or when you want to decide the moment a release pull request opens.

Choosing the mode#

Promoting a build#

A build waiting in staging shows Promote to production on the Staging row. Promoting pushes that build's generated output to scalar-generated, merges it into scalar-next, and opens the release pull request — exactly what an automatic build does, at a time you choose. Your custom code on scalar-next is preserved either way.

The pipeline card only ever offers the newest build, and the action clears once you have promoted it, so an older build cannot be pushed over one production already has. The version history offers each staged build on its own row, and warns you when the one you picked has been superseded by a newer build.

Switching back to automatic#

Turning Promote manually off ships the build already waiting, so production catches up instead of skipping it. Every build after that pushes on its own again.

[!NOTE] Unlinking a repository clears the promotion mode along with the rest of the link, so a repository you connect later starts out on automatic promotion.

Configuration equivalent#

{
  "targets": {
    "typescript": {
      "promotion": "manual"
    }
  }
}

Your custom code is preserved#

You can edit generated files in your repository on scalar-next. Scalar performs a three-way merge on every regeneration, so your changes are carried forward into the next release pull request instead of being overwritten. Review it as usual; only genuine conflicts need your attention. See Custom Code.

Repository prerequisites#

• Branch protection on scalar-next and the default branch must allow the Scalar app and the github-actions bot to push, or be left unprotected. The default branch only ever advances by merging a release pull request, and scalar-next receives each released state back from the release workflow.
• No Actions settings changes are required: the generated workflows declare their own permissions and never create pull requests.

Configuration equivalent#

Linking from the dashboard sets the target's destinations in your SDK configuration. You can also set it directly:

{
  "targets": {
    "typescript": {
      "destinations": {
        "production": {
          "repo": "acme/acme-typescript",
          "branch": "main"
        }
      }
    }
  }
}

Adding repository secrets#

OIDC trusted publishing needs no secrets. Token-based publishing, and Maven Central's GPG signing, store credentials as secrets on the SDK repository. The generated workflows read them by exact name, so the name has to match.

[!NOTE] Secrets are scoped to the repository. If you publish several targets from one repository, add each registry's secret to that same repository.

Unlink a repository#

To stop syncing, open the target, select Configure on the Production row, and use Unlink. Builds stop pushing to GitHub until you reconnect. Code already in the repository, and anything already published, is left untouched.