Release Please Standards

Release-Please Standards

When to Use This Skill

Version: 2025.1

Standard release-please configuration for automated semantic versioning and changelog generation.

Standard Configuration

GitHub Actions Workflow

File: .github/workflows/release-please.yml

The release PR needs a token that can trigger other workflows. Two patterns; the GitHub App token is preferred (the laurigates org standard), with the MY_RELEASE_PLEASE_TOKEN PAT kept as a legacy fallback.

GitHub App token (preferred) — create-github-app-token mints a token from RELEASE_PLEASE_APP_ID (variable) and RELEASE_PLEASE_PRIVATE_KEY (secret), which gitops provisions on repos flagged release_please = true:

name: Release Please

on:
  push:
    branches:
      - main

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/create-github-app-token@v3
        id: app-token
        with:
          app-id: ${{ vars.RELEASE_PLEASE_APP_ID }}
          private-key: ${{ secrets.RELEASE_PLEASE_PRIVATE_KEY }}
      - uses: googleapis/release-please-action@v4
        with:
          token: ${{ steps.app-token.outputs.token }}

PAT (legacy) — a MY_RELEASE_PLEASE_TOKEN secret in repository settings:

      - uses: googleapis/release-please-action@v5
        with:
          token: ${{ secrets.MY_RELEASE_PLEASE_TOKEN }}

Configuration Files

File: release-please-config.json

{
  "packages": {
    ".": {
      "release-type": "node",
      "changelog-sections": [
        {"type": "feat", "section": "Features"},
        {"type": "fix", "section": "Bug Fixes"},
        {"type": "perf", "section": "Performance"},
        {"type": "deps", "section": "Dependencies"},
        {"type": "docs", "section": "Documentation", "hidden": true},
        {"type": "chore", "section": "Miscellaneous", "hidden": true}
      ]
    }
  },
  "plugins": ["node-workspace"]
}

File: .release-please-manifest.json

{
  ".": "0.0.0"
}

Note: Version 0.0.0 is a placeholder - release-please updates this automatically.

Project Type Variations

Node.js Frontend/Backend

• release-type: node
• plugins: node-workspace
• Updates: package.json version field

Python Service

• release-type: python
• Updates: pyproject.toml version field, __version__ in code

Infrastructure (Helm)

• release-type: helm
• Updates: Chart.yaml version field

Multi-package Repository

Monorepos need component on every package and include-component-in-tag: true at the root, plus per-package extra-files and (optionally) the linked-versions plugin:

{
  "packages": {
    "packages/frontend": {"release-type": "node", "component": "frontend"},
    "packages/backend": {"release-type": "node", "component": "backend"}
  },
  "plugins": ["node-workspace"]
}

For the full monorepo strategy — component tagging, duplicate-tag / multiple-paths fixes, per-package extra-files path rules, linked versions, adding a package, and shared→component tag migration — see git-plugin:release-please-configuration.

Required Components

Minimum Requirements

1. Workflow file: .github/workflows/release-please.yml

• Uses googleapis/release-please-action@v5
• Token: GitHub App token (preferred) or MY_RELEASE_PLEASE_TOKEN secret
• Triggers on push to main

2. Config file: release-please-config.json

• Valid release-type for project
• changelog-sections defined

3. Manifest file: .release-please-manifest.json

• Lists all packages with current versions

Token Configuration

The workflow uses a dedicated release token (not GITHUB_TOKEN) because:

• Allows release PRs to trigger other workflows
• Enables CI checks on release PRs
• Maintains proper audit trail

Two token patterns are accepted:

A workflow already using the App-token pattern is compliant — do not flag it to switch to MY_RELEASE_PLEASE_TOKEN.

Compliance Checking

Status Levels

Validation Rules

1. Workflow validation:

• Action version: v5 (warn if older)
• Token: Must use secret, not hardcoded
• Trigger: Must include push to main

2. Config validation:

• release-type: Must be valid (node, python, helm, simple)
• changelog-sections: Must include feat and fix

3. Manifest validation:

• Must be valid JSON
• Packages must match config

Protected Files

IMPORTANT: Release-please manages these files automatically:

• CHANGELOG.md - Never edit manually
• Version fields in package.json, pyproject.toml, Chart.yaml
• .release-please-manifest.json - Only edit for initial setup

See release-please-protection skill for enforcement.

Conventional Commits

Release-please requires conventional commit messages:

Installation

1. Create workflow file 2. Create config file 3. Create manifest file 4. Provide the release token — preferred: set the RELEASE_PLEASE_APP_ID variable + RELEASE_PLEASE_PRIVATE_KEY secret (gitops provisions these on release_please = true repos); legacy: add MY_RELEASE_PLEASE_TOKEN to repository secrets 5. Ensure pre-commit has conventional-pre-commit hook

Troubleshooting

Release PR Not Created

• Check conventional commit format
• Verify workflow has correct permissions
• Ensure token has write access

Version Not Updated

• Check manifest file is valid JSON
• Verify release-type matches project
• Review release-please logs in Actions

CI Not Running on Release PR

• Token must be a dedicated release token (GitHub App token or PAT), not GITHUB_TOKEN
• Verify workflow trigger includes pull_request