# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# SPDX-License-Identifier: Apache-2.0
# ══════════════════════════════════════════════════════════════════════
# ReleaseKit: Java/Kotlin Release Pipeline (Gradle)
# ══════════════════════════════════════════════════════════════════════
#
# SAMPLE WORKFLOW — Copy to .github/workflows/releasekit-gradle.yml to use.
#
# This workflow implements a release pipeline for Java/Kotlin projects
# managed by Gradle (settings.gradle / settings.gradle.kts). It uses
# releasekit to automate:
#
# 1. PREPARE — compute version bumps, generate changelogs, open
# or update a Release PR.
# 2. RELEASE — tag the merge commit, create a GitHub Release.
# 3. PUBLISH — publish artifacts to Maven Central (via Sonatype
# OSSRH) in topological order with retry and
# verification.
#
# ── Automatic Flow ──────────────────────────────────────────────────
#
# push to main ──► releasekit prepare ──► Release PR
# (java/** or jvm/**) (autorelease: pending)
# │
# merge PR
# │
# ▼
# releasekit release ──► tags + GitHub Release
# │
# ▼
# releasekit publish ──► Maven Central
# │
# ▼
# repository_dispatch ──► downstream repos
#
# ── Manual Dispatch Flow ────────────────────────────────────────────
#
# ┌─────────────────────────────────────────────────────────────┐
# │ workflow_dispatch UI │
# │ │
# │ action: [prepare ▼] ──► runs PREPARE job only │
# │ [release ▼] ──► runs RELEASE + PUBLISH + NOTIFY │
# │ │
# │ target: [maven-central / staging] │
# │ dry_run: [✓] simulate, no side effects │
# │ force_prepare: [✓] skip preflight, force PR creation │
# │ group: [________] target a release group │
# │ bump_type: [auto / patch / minor / major] │
# │ prerelease: [________] e.g. rc.1, beta.1 │
# │ skip_publish: [✓] tag + release but don't publish │
# │ concurrency: [0] max parallel publish (0 = auto) │
# │ max_retries: [2] retry failed publishes │
# └─────────────────────────────────────────────────────────────┘
#
# ── Job Dependency Graph ───────────────────────────────────────────
#
# ┌───────┐
# │ auth │ Resolve token: App → PAT → GITHUB_TOKEN
# └───┬───┘
# │ outputs: token, auth-method, git-user-name, git-user-email
# │
# ├──────────────────────┐
# │ │
# ▼ ▼
# ┌─────────┐ ┌─────────┐
# │ prepare │ │ release │
# │ (push) │ │ (merge) │
# └─────────┘ └────┬────┘
# │ needs: [auth]
# │
# ▼
# ┌─────────┐
# │ publish │
# │ (Maven) │
# └────┬────┘
# │ needs: [auth, release]
# │
# ▼
# ┌────────┐
# │ verify │ Maven Central search check
# └────┬───┘
# │ needs: [publish]
# │
# ▼
# ┌────────┐
# │ notify │
# └────────┘
# needs: [auth, release, publish, verify]
#
# ── Token Resolution (Sentinel Pattern) ───────────────────────────
#
# The auth job resolves a token and outputs it for downstream jobs.
# Because secrets.GITHUB_TOKEN cannot cross job boundaries, the auth
# job outputs the literal string "GITHUB_TOKEN" as a sentinel when
# falling back to the built-in token.
#
# auth job downstream job
# ──────── ──────────────
# App token available?
# yes ──► output real token ──► use token directly
# no ──► PAT available?
# yes ──► output PAT ─► use token directly
# no ──► output ┌─────────────────────────────┐
# "GITHUB_TOKEN"│ RESOLVED_TOKEN = │
# (sentinel) │ auth-method == 'github- │
# │ token' ? secrets.GITHUB_ │
# │ TOKEN : needs.auth.token │
# └─────────────────────────────┘
#
# ── Trigger Matrix ──────────────────────────────────────────────────
#
# Event │ Jobs that run
# ───────────────────┼──────────────────────────────────
# push to main │ prepare
# PR merged │ release → publish → verify → notify
# dispatch: prepare │ prepare
# dispatch: release │ release → publish → verify → notify
#
# ── Inputs Reference ────────────────────────────────────────────────
#
# Input │ Type │ Default │ Description
# ───────────────┼─────────┼────────────────┼──────────────────────
# action │ choice │ release │ Pipeline stage
# target │ choice │ maven-central │ Registry target
# dry_run │ boolean │ true │ Simulate
# force_prepare │ boolean │ false │ Force PR creation
# group │ string │ (all) │ Release group
# bump_type │ choice │ auto │ Override bump
# prerelease │ string │ (none) │ Prerelease suffix
# skip_publish │ boolean │ false │ Skip registry
# concurrency │ string │ 0 │ Max parallel
# max_retries │ string │ 2 │ Retry count
# no_ai │ boolean │ false │ Disable AI features
# model │ string │ (chain) │ Override AI model
# codename_theme │ string │ (cfg) │ Override codename theme
#
# ── Required Configuration ─────────────────────────────────────────
#
# Repository Variables (Settings → Variables → Actions):
#
# RELEASEKIT_APP_ID — GitHub App ID (for App-based auth)
# RELEASEKIT_GIT_USER_NAME — Git committer name for CLA-signed
# identity (used with PAT/GITHUB_TOKEN)
# RELEASEKIT_GIT_USER_EMAIL— Git committer email for CLA-signed
# identity (used with PAT/GITHUB_TOKEN)
#
# Repository Secrets (Settings → Secrets → Actions):
#
# RELEASEKIT_APP_PRIVATE_KEY — GitHub App private key (PEM)
# RELEASEKIT_TOKEN — PAT fallback (if no App configured)
# GEMINI_API_KEY — Gemini API key (for AI features)
# OSSRH_USERNAME — Sonatype OSSRH username
# OSSRH_PASSWORD — Sonatype OSSRH password/token
# GPG_SIGNING_KEY — GPG private key (base64-encoded)
# GPG_PASSPHRASE — GPG key passphrase
#
# If neither RELEASEKIT_APP_ID nor RELEASEKIT_TOKEN is set, the
# workflow falls back to GITHUB_TOKEN. In that case, set
# RELEASEKIT_GIT_USER_NAME and RELEASEKIT_GIT_USER_EMAIL to use
# a CLA-signed identity (otherwise PRs may fail CLA checks).
#
# ── Idempotency & Resumability ─────────────────────────────────────
#
# Every job is idempotent — re-running a failed workflow is safe:
#
# auth Stateless; always resolves a fresh token.
# prepare Updates the existing Release PR instead of duplicating.
# release Skips tags and GitHub Releases that already exist.
# publish Skips versions already present on Maven Central.
# verify Re-verifies; always safe to repeat.
# notify Dispatches repository_dispatch (downstream deduplicates).
#
# To resume after a failure, use "Re-run failed jobs" in the GitHub
# Actions UI. Only the failed jobs re-run; successful jobs keep their
# outputs. No special flags or state files are needed.
#
# ══════════════════════════════════════════════════════════════════════
name: "ReleaseKit: Java (Gradle)"
on:
workflow_call:
inputs:
action:
description: 'Which pipeline stage to run'
required: false
default: release
type: string
target:
description: 'Publish target registry'
required: false
default: maven-central
type: string
dry_run:
description: 'Dry run'
required: false
default: true
type: boolean
force_prepare:
description: 'Force PR creation'
required: false
default: false
type: boolean
group:
description: 'Release group'
required: false
type: string
bump_type:
description: 'Override bump type'
required: false
default: auto
type: string
prerelease:
description: 'Prerelease suffix'
required: false
type: string
skip_publish:
description: 'Skip publishing to Maven Central'
required: false
default: false
type: boolean
concurrency:
description: 'Max parallel publish jobs'
required: false
default: '0'
type: string
max_retries:
description: 'Max retries'
required: false
default: '2'
type: string
no_ai:
description: 'Disable all AI features'
required: false
default: false
type: boolean
model:
description: 'Override AI model'
required: false
default: ''
type: string
codename_theme:
description: 'Override codename theme'
required: false
default: ''
type: string
secrets:
GITHUB_TOKEN:
required: false
OSSRH_USERNAME:
required: false
OSSRH_PASSWORD:
required: false
GPG_SIGNING_KEY:
required: false
GPG_PASSPHRASE:
required: false
GEMINI_API_KEY:
required: false
RELEASEKIT_APP_PRIVATE_KEY:
description: 'GitHub App private key for CLA-passing commits'
required: false
RELEASEKIT_TOKEN:
description: 'Personal Access Token fallback'
required: false
workflow_dispatch:
inputs:
action:
description: 'Which pipeline stage to run'
required: true
default: release
type: choice
options:
- prepare
- release
target:
description: 'Publish target registry (release only)'
required: true
default: maven-central
type: choice
options:
- maven-central
- staging
dry_run:
description: 'Dry run — log what would happen without creating tags or publishing'
required: true
default: true
type: boolean
force_prepare:
description: 'Force create/update the Release PR even if no new bumps are detected'
required: false
default: false
type: boolean
group:
description: 'Release group to target (leave empty for all)'
required: false
type: string
bump_type:
description: 'Override auto-detected bump type'
required: false
default: auto
type: choice
options:
- auto
- patch
- minor
- major
prerelease:
description: 'Publish as prerelease (e.g. rc.1, beta.1)'
required: false
type: string
skip_publish:
description: 'Tag and create GitHub Release but skip publishing to Maven Central'
required: false
default: false
type: boolean
concurrency:
description: 'Max parallel publish jobs (0 = auto)'
required: false
default: '0'
type: string
max_retries:
description: 'Max retries for failed publish attempts (0 = no retries)'
required: false
default: '2'
type: string
no_ai:
description: 'Disable all AI features (summarization, codenames)'
required: false
default: false
type: boolean
model:
description: 'Override AI model (e.g. ollama/gemma3:12b)'
required: false
type: string
codename_theme:
description: 'Override codename theme (e.g. galaxies, animals)'
required: false
type: string
auth_method:
description: 'Authentication method (auto = detect from configured secrets)'
required: false
default: auto
type: choice
options:
- auto
- app
- pat
- github-token
push:
branches: [main]
paths:
- "java/**"
- "jvm/**"
pull_request:
types: [closed]
branches: [main]
# Only one release pipeline runs at a time.
concurrency:
group: releasekit-java-${{ github.ref }}
cancel-in-progress: false
permissions:
contents: write
pull-requests: write
id-token: write # Sigstore keyless signing (SLSA provenance)
env:
RELEASEKIT_DIR: py/tools/releasekit
WORKSPACE_DIR: java
JAVA_VERSION: "17"
GRADLE_VERSION: "8.7"
DRY_RUN: ${{ github.event_name == 'pull_request' && 'false' || (inputs.dry_run == 'false' && 'false' || 'true') }}
jobs:
# ═══════════════════════════════════════════════════════════════════════
# AUTH: Resolve token (GitHub App → PAT → GITHUB_TOKEN)
# ═══════════════════════════════════════════════════════════════════════
auth:
name: Resolve Auth Token
runs-on: ubuntu-latest
timeout-minutes: 2
outputs:
token: ${{ steps.resolve.outputs.token }}
auth-method: ${{ steps.resolve.outputs.auth-method }}
git-user-name: ${{ steps.resolve.outputs.git-user-name }}
git-user-email: ${{ steps.resolve.outputs.git-user-email }}
steps:
- name: Generate GitHub App token
if: >
(inputs.auth_method == 'auto' || inputs.auth_method == 'app' || inputs.auth_method == '')
&& vars.RELEASEKIT_APP_ID != ''
id: app-token
uses: actions/create-github-app-token@v2
with:
app-id: ${{ vars.RELEASEKIT_APP_ID }}
private-key: ${{ secrets.RELEASEKIT_APP_PRIVATE_KEY }}
- name: Get App bot user ID
if: steps.app-token.outcome == 'success'
id: app-user
run: |
if ! user_id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id 2>/dev/null); then
echo "::warning::Failed to fetch App bot user ID — using 0 as fallback"
user_id=0
fi
echo "user-id=$user_id" >> "$GITHUB_OUTPUT"
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
# Resolve: App > PAT > GITHUB_TOKEN (respects auth_method override).
- name: Resolve token and identity
id: resolve
run: |
AUTH="${{ inputs.auth_method || 'auto' }}"
# App token — used when auth=auto (and available) or auth=app.
if [ "$AUTH" = "app" ] || { [ "$AUTH" = "auto" ] && [ -n "$APP_TOKEN" ]; }; then
{ echo "token=$APP_TOKEN"
echo "auth-method=app"
echo "git-user-name=${{ steps.app-token.outputs.app-slug }}[bot]"
echo "git-user-email=${{ steps.app-user.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com"
} >> "$GITHUB_OUTPUT"
echo "::notice::Using GitHub App token (${{ steps.app-token.outputs.app-slug }})"
# PAT — used when auth=auto (and available) or auth=pat.
elif [ "$AUTH" = "pat" ] || { [ "$AUTH" = "auto" ] && [ -n "$PAT_TOKEN" ]; }; then
{ echo "token=$PAT_TOKEN"
echo "auth-method=pat"
echo "git-user-name=${GIT_USER_NAME:-releasekit[bot]}"
echo "git-user-email=${GIT_USER_EMAIL:-releasekit[bot]@users.noreply.github.com}"
} >> "$GITHUB_OUTPUT"
echo "::notice::Using Personal Access Token"
# GITHUB_TOKEN — fallback or explicit. Uses repo variables for
# git identity if set, so CLA can pass with a signed identity.
# NOTE: We output the sentinel "GITHUB_TOKEN" instead of the
# actual secret because secrets.GITHUB_TOKEN cannot be passed
# across job boundaries via outputs.
else
{ echo "token=GITHUB_TOKEN"
echo "auth-method=github-token"
echo "git-user-name=${GIT_USER_NAME:-github-actions[bot]}"
echo "git-user-email=${GIT_USER_EMAIL:-github-actions[bot]@users.noreply.github.com}"
} >> "$GITHUB_OUTPUT"
if [ -n "$GIT_USER_NAME" ]; then
echo "::notice::Using GITHUB_TOKEN with custom identity ($GIT_USER_NAME)"
else
echo "::warning::Using GITHUB_TOKEN — PRs will not trigger CI and may fail CLA checks. Set RELEASEKIT_GIT_USER_NAME and RELEASEKIT_GIT_USER_EMAIL repo variables to use a CLA-signed identity."
fi
fi
env:
APP_TOKEN: ${{ steps.app-token.outputs.token }}
PAT_TOKEN: ${{ secrets.RELEASEKIT_TOKEN }}
GIT_USER_NAME: ${{ vars.RELEASEKIT_GIT_USER_NAME }}
GIT_USER_EMAIL: ${{ vars.RELEASEKIT_GIT_USER_EMAIL }}
# ═══════════════════════════════════════════════════════════════════════
# PREPARE: Compute bumps and open/update Release PR
# ═══════════════════════════════════════════════════════════════════════
prepare:
name: Prepare Release PR
needs: auth
if: |
(github.event_name == 'push' &&
!startsWith(github.event.head_commit.message, 'chore(release):') &&
!contains(github.event.head_commit.message, 'releasekit--release')) ||
(github.event_name == 'workflow_dispatch' && inputs.action == 'prepare')
runs-on: ubuntu-latest
timeout-minutes: 10
outputs:
has_bumps: ${{ steps.prepare.outputs.has_bumps }}
pr_url: ${{ steps.prepare.outputs.pr_url }}
env:
RESOLVED_TOKEN: ${{ needs.auth.outputs.auth-method == 'github-token' && secrets.GITHUB_TOKEN || needs.auth.outputs.token }}
steps:
- uses: actions/checkout@v6
- uses: ./.github/actions/setup-releasekit
with:
token: ${{ env.RESOLVED_TOKEN }}
releasekit-dir: ${{ env.RELEASEKIT_DIR }}
git-user-name: ${{ needs.auth.outputs.git-user-name }}
git-user-email: ${{ needs.auth.outputs.git-user-email }}
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: ${{ env.JAVA_VERSION }}
- uses: gradle/actions/setup-gradle@v4
with:
gradle-version: ${{ env.GRADLE_VERSION }}
- uses: ./.github/actions/run-releasekit
id: prepare
with:
command: prepare
workspace: java
releasekit-dir: ${{ env.RELEASEKIT_DIR }}
group: ${{ inputs.group }}
bump-type: ${{ inputs.bump_type }}
prerelease: ${{ inputs.prerelease }}
force: ${{ inputs.force_prepare }}
no-ai: ${{ inputs.no_ai && 'true' || 'false' }}
model: ${{ inputs.model }}
codename-theme: ${{ inputs.codename_theme }}
env:
GH_TOKEN: ${{ env.RESOLVED_TOKEN }}
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
# ═══════════════════════════════════════════════════════════════════════
# RELEASE: Tag merge commit and create GitHub Release
# ═══════════════════════════════════════════════════════════════════════
release:
name: Tag and Release
needs: auth
if: |
(github.event_name == 'pull_request' &&
github.event.pull_request.merged == true &&
contains(github.event.pull_request.labels.*.name, 'autorelease: pending')) ||
(github.event_name == 'workflow_dispatch' && inputs.action == 'release')
runs-on: ubuntu-latest
timeout-minutes: 10
outputs:
release_url: ${{ steps.release.outputs.release_url }}
env:
RESOLVED_TOKEN: ${{ needs.auth.outputs.auth-method == 'github-token' && secrets.GITHUB_TOKEN || needs.auth.outputs.token }}
steps:
- uses: actions/checkout@v6
- uses: ./.github/actions/setup-releasekit
with:
token: ${{ env.RESOLVED_TOKEN }}
releasekit-dir: ${{ env.RELEASEKIT_DIR }}
git-user-name: ${{ needs.auth.outputs.git-user-name }}
git-user-email: ${{ needs.auth.outputs.git-user-email }}
- uses: ./.github/actions/run-releasekit
id: release
with:
command: release
workspace: java
releasekit-dir: ${{ env.RELEASEKIT_DIR }}
dry-run: ${{ env.DRY_RUN }}
show-plan: "true"
no-ai: ${{ inputs.no_ai && 'true' || 'false' }}
model: ${{ inputs.model }}
codename-theme: ${{ inputs.codename_theme }}
env:
GH_TOKEN: ${{ env.RESOLVED_TOKEN }}
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
# ═══════════════════════════════════════════════════════════════════════
# PUBLISH: Build and publish artifacts to Maven Central
# ═══════════════════════════════════════════════════════════════════════
publish:
name: Publish to ${{ inputs.target || 'maven-central' }}
needs: [auth, release]
if: inputs.skip_publish != 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
env:
RESOLVED_TOKEN: ${{ needs.auth.outputs.auth-method == 'github-token' && secrets.GITHUB_TOKEN || needs.auth.outputs.token }}
steps:
- uses: actions/checkout@v6
- uses: ./.github/actions/setup-releasekit
with:
token: ${{ env.RESOLVED_TOKEN }}
releasekit-dir: ${{ env.RELEASEKIT_DIR }}
enable-ollama: "false"
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: ${{ env.JAVA_VERSION }}
- uses: gradle/actions/setup-gradle@v4
with:
gradle-version: ${{ env.GRADLE_VERSION }}
- name: Import GPG signing key
run: |
echo "${{ secrets.GPG_SIGNING_KEY }}" | base64 -d | gpg --batch --import
env:
GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
- name: Build Java artifacts
working-directory: ${{ env.WORKSPACE_DIR }}
run: gradle build --no-daemon
- uses: ./.github/actions/run-releasekit
with:
command: publish
workspace: java
releasekit-dir: ${{ env.RELEASEKIT_DIR }}
dry-run: ${{ env.DRY_RUN }}
force: "true"
group: ${{ inputs.group }}
concurrency: ${{ inputs.concurrency }}
max-retries: ${{ inputs.max_retries }}
show-plan: "true"
no-ai: ${{ inputs.no_ai && 'true' || 'false' }}
model: ${{ inputs.model }}
codename-theme: ${{ inputs.codename_theme }}
env:
OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
OSSRH_PASSWORD: ${{ secrets.OSSRH_PASSWORD }}
GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
- name: Upload manifest artifact
if: success()
uses: actions/upload-artifact@v4
with:
name: release-manifest-java
path: ${{ env.WORKSPACE_DIR }}/release-manifest.json
retention-days: 90
# ═══════════════════════════════════════════════════════════════════════
# VERIFY: Check published artifacts are available on Maven Central
# ═══════════════════════════════════════════════════════════════════════
verify:
name: Verify Published Artifacts
needs: publish
if: >-
success() &&
(github.event_name == 'pull_request' ||
inputs.dry_run == false)
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: ${{ env.JAVA_VERSION }}
- name: Wait for Maven Central propagation
run: |
echo "Waiting 60 seconds for Maven Central sync..."
sleep 60
- name: Verify artifact is available
continue-on-error: true # Propagation delays should not fail the pipeline
run: |
# Check Maven Central search API for the artifact.
curl -sf "https://search.maven.org/solrsearch/select?q=g:com.google.genkit&rows=1" \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Found {d[\"response\"][\"numFound\"]} artifacts'); sys.exit(0 if d['response']['numFound']>0 else 1)"
echo "✅ Maven Central verification complete"
# ═══════════════════════════════════════════════════════════════════════
# NOTIFY: Post-release notifications
# ═══════════════════════════════════════════════════════════════════════
notify:
name: Notify Downstream
needs: [auth, release, publish, verify]
if: success()
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Dispatch release event
uses: peter-evans/repository-dispatch@v3
with:
token: ${{ needs.auth.outputs.auth-method == 'github-token' && secrets.GITHUB_TOKEN || needs.auth.outputs.token }}
event-type: genkit-java-release
client-payload: '{"release_url": "${{ needs.release.outputs.release_url }}"}'
