Release

Source: src/GitHub/Release.ts

A GitHub release.

Release manages repository releases (tagged versions with notes, binaries, etc.). Releases are created on first deploy and updated in place on subsequent deploys when properties change. Publishing a draft converts it to a public release.

Authentication is resolved via the GitHubCredentials service supplied by GitHub.providers() (env, stored PAT, gh CLI, or OAuth). The token needs repo scope for private repositories or public_repo for public ones.

Creating Releases

Basic Release

const v1 = yield* GitHub.Release("v1", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.0.0",
  name: "Version 1.0.0",
  body: "First stable release",
});

Prerelease

yield* GitHub.Release("beta", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v2.0.0-beta.1",
  name: "v2.0.0 Beta 1",
  body: "Beta release for testing",
  prerelease: true,
});

Draft Releases

// First deploy: create as draft
const release = yield* GitHub.Release("v1", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.0.0",
  name: "Version 1.0.0",
  body: "Release notes here",
  draft: true,
});

// Later deploy: publish by setting draft: false
const release = yield* GitHub.Release("v1", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.0.0",
  name: "Version 1.0.0",
  body: "Release notes here",
  draft: false,
});

Auto-Generated Release Notes

yield* GitHub.Release("v1", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.1.0",
  name: "Version 1.1.0",
  generateReleaseNotes: true,
});

Targeting Specific Commits

yield* GitHub.Release("hotfix", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.0.1",
  name: "Hotfix 1.0.1",
  body: "Critical bug fix",
  targetCommitish: "hotfix-branch",
});

Updating Releases

Deploy with the same logical ID and tag to update the existing release.

yield* GitHub.Release("v1", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.0.0",
  name: "Version 1.0.0",
  body: `
    # What's New

    - Feature A
    - Feature B
    - Bug fixes
  `,
});

Replacing on Tag Change

Changing the tag creates a new release and deletes the old one.

// First deploy creates v1.0.0
const release = yield* GitHub.Release("latest", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.0.0",
});

// Later deploy with different tag replaces it
const release = yield* GitHub.Release("latest", {
  owner: "my-org",
  repository: "my-repo",
  tagName: "v1.1.0",
});

Wiring with Other Resources

import * as Output from "alchemy/Output";

const repo = yield* GitHub.Repository("sdk", {
  owner: "my-org",
  name: "sdk",
  autoInit: true,
});

yield* GitHub.Release("v1", {
  owner: "my-org",
  repository: Output.map(repo.fullName, (fullName) => fullName.split("/")[1]!),
  tagName: "v1.0.0",
  name: "Initial Release",
  body: "First public version of the SDK",
});