automated-release-setup

name	automated-release-setup
description	Use this skill whenever the user asks to "set up automated release", "configure release automation", "add automated release workflow", or any variation of setting up the automated release workflow for a SonarSource analyzer project. This skill gathers project details, creates workflow files, updates existing release workflows, and sets up vault permissions.

Setup Automated Release Workflow

Help the user set up the automated release workflow by gathering required information and creating the necessary workflow files.

Step 1: Gather Required Information

Ask the user for the following details using AskUserQuestion:

1. Project Name: Display name (e.g., "SonarCOBOL", "SonarApex")
2. Plugin Name: Short identifier used in secrets (e.g., "cobol", "apex")
3. Jira Project Key: Jira project key (e.g., "SONARCOBOL", "SONARAPEX")
4. PM Email: Product Manager email address
5. Slack Channel: Check the existing release.yml for slackChannel value first - reuse it if present, otherwise ask the user
6. Build System: Maven (pom.xml) or Gradle (gradle.properties)
7. SonarQube for IDE Integration: Whether to create integration tickets for SonarQube for IDE:
   • SLVS (SonarQube for Visual Studio)
   • SLVSCODE (SonarQube for VS Code)
   • SLCORE (SonarLint Core)
   • SLE (SonarQube for Eclipse)
   • SLI (SonarQube for IntelliJ)
8. CLI Integration: Whether to create an integration ticket for the SonarQube CLI scanner.
9. Version Bump: Whether the automated release workflow should bump the project version after the release (i.e., prepare the next development iteration). If yes, also ask:
   • Bump Version PR Labels: Optional comma-separated list of labels to apply to the version bump pull request (e.g., update-next-dev,skip-qa). Leave empty if no labels are needed.

Step 1b: Check Existing release.yml

Before asking for all information, read the existing .github/workflows/release.yml file to extract:

• slackChannel: Reuse the existing Slack channel configuration for the automated release workflow

This ensures consistency between the release and automated-release workflows.

Step 1c: Detect Workflow File Extension

Before creating any workflow files, check whether the existing workflows in .github/workflows/ use .yml or .yaml as the file extension:

ls .github/workflows/

• If most existing files use .yml, create new workflow files with the .yml extension.
• If most existing files use .yaml, create new workflow files with the .yaml extension.
• If there is a mix, prefer .yml (GitHub Actions default).

Apply this detected extension consistently when naming all new workflow files (e.g., automated-release.yml or automated-release.yaml).

Step 2: Check Prerequisites

Remind the user of these prerequisites and ask for confirmation using AskUserQuestion:

1. Jira Configuration:

   • Add Jira Tech User GitHub as Administrator on the Jira project
   • Add the same user to Jira sandbox for dry-run testing (required for dry-run: true mode)
   • Ask the user to confirm both:
     • "Have you added 'Jira Tech User GitHub' as Administrator on the {JIRA_PROJECT_KEY} project?" (Production)
     • "Have you added 'Jira Tech User GitHub' as Administrator on the {JIRA_PROJECT_KEY} project in the Jira sandbox?" (For dry-run testing)
   • The user must verify this manually at: Project settings → People → Administrator role
   • Sandbox URL: https://sonarsource-sandbox-608.atlassian.net/

2. Vault Permissions (re-terraform-aws-vault):

   • Create a PR to add the release-automation secret to the repository's config in the squad config file
   • File: orders/{squad}.yaml (e.g., orders/analysis-jvm-squad.yaml)
   • This creates secret sonar-{plugin-name}-release-automation
   • Example PR: https://github.com/SonarSource/re-terraform-aws-vault/pull/8406
   • Important: The skill should create this PR automatically (see Step 5b)

3. Release Workflow:

   • Ensure release.yml supports workflow_dispatch with inputs: version, releaseId, dryRun

Step 3: Create Workflow Files

Create only the automated-release workflow file (using the detected extension from Step 1c). Do not create a separate bump-versions workflow — version bumping is handled directly by the reusable workflow when bump-version: true is passed.

3.1 Create automated-release{EXT} (standard, no SonarQube for IDE integration, no version bump)

name: Automated Release
on:
  workflow_dispatch:
    inputs:
      short-description:
        description: "Short description for the REL ticket"
        required: true
        type: string
      sqc-integration:
        description: "Integrate into SQC"
        type: boolean
        default: true
      sqs-integration:
        description: "Integrate into SQS"
        type: boolean
        default: true
      branch:
        description: "Branch from which to do the release"
        required: true
        default: "master"
        type: string
      new-version:
        description: "Next Jira version to create after the release (e.g. 2.2), NOT the version being released; if left empty, the current Jira version's last component is incremented (e.g. 2.1 -> 2.2)"
        required: false
        type: string
      rule-props-changed:
        description: >
          "@RuleProperty" changed? See SC-4654
        type: boolean
        default: false
      verbose:
        description: "Enable verbose logging"
        type: boolean
        default: false
      dry-run:
        description: "Test mode: uses Jira sandbox and creates draft GitHub release"
        type: boolean
        default: false

jobs:
  release:
    name: Release
    uses: SonarSource/release-github-actions/.github/workflows/automated-release.yml@v1
    permissions:
      statuses: read
      id-token: write
      contents: write
      actions: write
      pull-requests: write
    with:
      project-name: "${PROJECT_NAME}"
      plugin-name: "${PLUGIN_NAME}"
      jira-project-key: "${JIRA_PROJECT_KEY}"
      rule-props-changed: ${{ github.event.inputs.rule-props-changed }}
      short-description: ${{ github.event.inputs.short-description }}
      new-version: ${{ github.event.inputs.new-version }}
      sqc-integration: ${{ github.event.inputs.sqc-integration == 'true' }}
      sqs-integration: ${{ github.event.inputs.sqs-integration == 'true' }}
      branch: ${{ github.event.inputs.branch }}
      pm-email: "${PM_EMAIL}"
      slack-channel: "${SLACK_CHANNEL}"
      verbose: ${{ github.event.inputs.verbose == 'true' }}
      use-jira-sandbox: ${{ github.event.inputs.dry-run == 'true' }}
      is-draft-release: ${{ github.event.inputs.dry-run == 'true' }}

3.2 Create automated-release{EXT} (standard, no SonarQube for IDE integration, with version bump)

When the user wants version bumping, add bump-version: true (and optionally bump-version-pr-labels) to the with: block:

name: Automated Release
on:
  workflow_dispatch:
    inputs:
      short-description:
        description: "Short description for the REL ticket"
        required: true
        type: string
      sqc-integration:
        description: "Integrate into SQC"
        type: boolean
        default: true
      sqs-integration:
        description: "Integrate into SQS"
        type: boolean
        default: true
      branch:
        description: "Branch from which to do the release"
        required: true
        default: "master"
        type: string
      new-version:
        description: "Next Jira version to create after the release (e.g. 2.2), NOT the version being released; if left empty, the current Jira version's last component is incremented (e.g. 2.1 -> 2.2)"
        required: false
        type: string
      rule-props-changed:
        description: >
          "@RuleProperty" changed? See SC-4654
        type: boolean
        default: false
      verbose:
        description: "Enable verbose logging"
        type: boolean
        default: false
      dry-run:
        description: "Test mode: uses Jira sandbox and creates draft GitHub release"
        type: boolean
        default: false

jobs:
  release:
    name: Release
    uses: SonarSource/release-github-actions/.github/workflows/automated-release.yml@v1
    permissions:
      statuses: read
      id-token: write
      contents: write
      actions: write
      pull-requests: write
    with:
      project-name: "${PROJECT_NAME}"
      plugin-name: "${PLUGIN_NAME}"
      jira-project-key: "${JIRA_PROJECT_KEY}"
      rule-props-changed: ${{ github.event.inputs.rule-props-changed }}
      short-description: ${{ github.event.inputs.short-description }}
      new-version: ${{ github.event.inputs.new-version }}
      sqc-integration: ${{ github.event.inputs.sqc-integration == 'true' }}
      sqs-integration: ${{ github.event.inputs.sqs-integration == 'true' }}
      branch: ${{ github.event.inputs.branch }}
      pm-email: "${PM_EMAIL}"
      slack-channel: "${SLACK_CHANNEL}"
      verbose: ${{ github.event.inputs.verbose == 'true' }}
      use-jira-sandbox: ${{ github.event.inputs.dry-run == 'true' }}
      is-draft-release: ${{ github.event.inputs.dry-run == 'true' }}
      bump-version: true
      bump-version-pr-labels: "${BUMP_VERSION_PR_LABELS}"  # omit this line if no labels

3.3 Create automated-release{EXT} (with SonarQube for IDE integration, no version bump)

name: Automated Release
on:
  workflow_dispatch:
    inputs:
      short-description:
        description: "Short description for the REL ticket"
        required: true
        type: string
      sq-ide-short-description:
        description: "Short description for the SonarQube for IDE tickets (leave empty to skip IDE tickets)"
        required: false
        type: string
      sqc-integration:
        description: "Integrate into SQC"
        type: boolean
        default: true
      sqs-integration:
        description: "Integrate into SQS"
        type: boolean
        default: true
      slvs-integration:
        description: "Create SLVS ticket (SonarQube for Visual Studio)"
        type: boolean
        default: false
      slvscode-integration:
        description: "Create SLVSCODE ticket (SonarQube for VS Code)"
        type: boolean
        default: false
      slcore-integration:
        description: "Create SLCORE ticket (SonarLint Core)"
        type: boolean
        default: false
      sle-integration:
        description: "Create SLE ticket (SonarQube for Eclipse)"
        type: boolean
        default: false
      sli-integration:
        description: "Create SLI ticket (SonarQube for IntelliJ)"
        type: boolean
        default: false
      branch:
        description: "Branch from which to do the release"
        required: true
        default: "master"
        type: string
      new-version:
        description: "Next Jira version to create after the release (e.g. 2.2), NOT the version being released; if left empty, the current Jira version's last component is incremented (e.g. 2.1 -> 2.2)"
        required: false
        type: string
      rule-props-changed:
        description: >
          "@RuleProperty" changed? See SC-4654
        type: boolean
        default: false
      verbose:
        description: "Enable verbose logging"
        type: boolean
        default: false
      dry-run:
        description: "Test mode: uses Jira sandbox and creates draft GitHub release"
        type: boolean
        default: false

jobs:
  release:
    name: Release
    uses: SonarSource/release-github-actions/.github/workflows/automated-release.yml@v1
    permissions:
      statuses: read
      id-token: write
      contents: write
      actions: write
      pull-requests: write
    with:
      project-name: "${PROJECT_NAME}"
      plugin-name: "${PLUGIN_NAME}"
      jira-project-key: "${JIRA_PROJECT_KEY}"
      rule-props-changed: ${{ github.event.inputs.rule-props-changed }}
      short-description: ${{ github.event.inputs.short-description }}
      new-version: ${{ github.event.inputs.new-version }}
      sqc-integration: ${{ github.event.inputs.sqc-integration == 'true' }}
      sqs-integration: ${{ github.event.inputs.sqs-integration == 'true' }}
      create-slvs-ticket: ${{ github.event.inputs.slvs-integration == 'true' }}
      create-slvscode-ticket: ${{ github.event.inputs.slvscode-integration == 'true' }}
      create-slcore-ticket: ${{ github.event.inputs.slcore-integration == 'true' }}
      create-sle-ticket: ${{ github.event.inputs.sle-integration == 'true' }}
      create-sli-ticket: ${{ github.event.inputs.sli-integration == 'true' }}
      sq-ide-short-description: ${{ github.event.inputs.sq-ide-short-description }}
      branch: ${{ github.event.inputs.branch }}
      pm-email: "${PM_EMAIL}"
      slack-channel: "${SLACK_CHANNEL}"
      verbose: ${{ github.event.inputs.verbose == 'true' }}
      use-jira-sandbox: ${{ github.event.inputs.dry-run == 'true' }}
      is-draft-release: ${{ github.event.inputs.dry-run == 'true' }}

3.4 Create automated-release{EXT} (with SonarQube for IDE integration and version bump)

Add bump-version: true (and optionally bump-version-pr-labels) to the SonarQube for IDE variant's with: block, same as in 3.2.

3.5 Create automated-release{EXT} (with SQ-CLI integration, no version bump, no SonarQube for IDE integration)

name: Automated Release
on:
  workflow_dispatch:
    inputs:
      short-description:
        description: "Short description for the REL ticket"
        required: true
        type: string
      cli-integration:
        description: "Create CLI ticket (SonarQube CLI scanner)"
        type: boolean
        default: false
      sq-cli-short-description:
        description: "Short description for the CLI ticket (leave empty to use the main short-description)"
        required: false
        type: string
      sqc-integration:
        description: "Integrate into SQC"
        type: boolean
        default: true
      sqs-integration:
         description: "Integrate into SQS"
         type: boolean
         default: true
      branch:
        description: "Branch from which to do the release"
        required: true
        default: "master"
        type: string
      new-version:
        description: "Next Jira version to create after the release (e.g. 2.2), NOT the version being released; if left empty, the current Jira version's last component is incremented (e.g. 2.1 -> 2.2)"
        required: false
        type: string
      rule-props-changed:
        description: >
          "@RuleProperty" changed? See SC-4654
        type: boolean
        default: false
      verbose:
        description: "Enable verbose logging"
        type: boolean
        default: false
      dry-run:
        description: "Test mode: uses Jira sandbox and creates draft GitHub release"
        type: boolean
        default: false

jobs:
  release:
    name: Release
    uses: SonarSource/release-github-actions/.github/workflows/automated-release.yml@v1
    permissions:
      statuses: read
      id-token: write
      contents: write
      actions: write
      pull-requests: write
    with:
      project-name: "${PROJECT_NAME}"
      plugin-name: "${PLUGIN_NAME}"
      jira-project-key: "${JIRA_PROJECT_KEY}"
      rule-props-changed: ${{ github.event.inputs.rule-props-changed }}
      short-description: ${{ github.event.inputs.short-description }}
      new-version: ${{ github.event.inputs.new-version }}
      create-cli-ticket: ${{ github.event.inputs.cli-integration == 'true' }}
      sq-cli-short-description: ${{ github.event.inputs.sq-cli-short-description }}
      sqc-integration: ${{ github.event.inputs.sqc-integration == 'true' }}
      sqs-integration: ${{ github.event.inputs.sqs-integration == 'true' }}
      branch: ${{ github.event.inputs.branch }}
      pm-email: "${PM_EMAIL}"
      slack-channel: "${SLACK_CHANNEL}"
      verbose: ${{ github.event.inputs.verbose == 'true' }}
      use-jira-sandbox: ${{ github.event.inputs.dry-run == 'true' }}
      is-draft-release: ${{ github.event.inputs.dry-run == 'true' }}

Step 4: Update release.yml

The existing release.yml must be updated to support workflow_dispatch triggering from the automated release workflow. gh-action_release v7 uses a draft-first flow — it no longer needs a releaseId and no longer uses the release: published event.

Update the triggers to use workflow_dispatch only:

on:
  workflow_dispatch:
    inputs:
      version:
        type: string
        description: Full version including build number (e.g. 1.2.3.456)
        required: true
      dryRun:
        type: boolean
        description: Flag to enable the dry-run execution
        default: false

Then update the job's with: block to reference v7 and pass the inputs:

jobs:
  release:
    # ... existing permissions ...
    uses: SonarSource/gh-action_release/.github/workflows/main.yaml@v7
    with:
      # ... existing inputs like publishToBinaries, mavenCentralSync, slackChannel ...
      version: ${{ inputs.version }}
      dryRun: ${{ inputs.dryRun == true }}

Note: v7 no longer requires releaseId — it creates or reuses a draft release internally and publishes it atomically after successful artifact promotion.

Step 5: Create Branch and Commit

After creating/modifying all workflow files, create a branch and commit the changes:

# Create a new branch
git checkout -b add-automated-release-workflow

# Stage the workflow files (use the correct extension detected in Step 1c)
git add .github/workflows/automated-release.yml .github/workflows/release.yml

# Commit with descriptive message
git commit -m "Add automated release workflow

Add workflow for automated release process:
- automated-release.yml: Main workflow that orchestrates the release
- Update release.yml to support workflow_dispatch for automated releases
"

Step 5b: Create PR for Vault Permissions (re-terraform-aws-vault)

Create a PR in the re-terraform-aws-vault repository to add the release-automation secret:

1. Clone the repository:

   gh repo clone SonarSource/re-terraform-aws-vault /tmp/re-terraform-aws-vault --depth 1
   

2. Find the squad configuration file that contains the repository (e.g., orders/analysis-jvm-squad.yaml)

3. Check if a release_automation YAML anchor already exists at the top of the file. If not, add it after the other anchors (like github_lock):

   release_automation: &release_automation
     suffix: release-automation
     description: access to sonar-enterprise and sonarcloud-core repositories to create PRs to update analyzers
     organization: SonarSource
     permissions:
       contents: write
       pull_requests: write
   

4. Add the release-automation secret to the repository's github.customs section using the anchor:

   - <<: *release_automation
     repositories: [${REPO_NAME}, sonar-enterprise, sonarcloud-core]
   

   Important: Include the repository itself (e.g., sonar-apex) in the repositories list along with sonar-enterprise and sonarcloud-core.

5. Create branch, commit, and PR:

   cd /tmp/re-terraform-aws-vault
   git checkout -b add-release-automation-${REPO_NAME}
   git add orders/${SQUAD_CONFIG_FILE}
   git commit -m "Add release-automation secret for ${REPO_NAME}
   
   This enables the automated release workflow to create PRs
   in sonar-enterprise and sonarcloud-core repositories."
   git push -u origin add-release-automation-${REPO_NAME}
   gh pr create --title "Add release-automation secret for ${REPO_NAME}" --body "## Summary
   - Add release-automation secret for ${REPO_NAME} to enable automated release workflow
   - This creates the secret \`sonar-${PLUGIN_NAME}-release-automation\` which allows creating PRs in sonar-enterprise and sonarcloud-core
   
   ## Test plan
   - [ ] Verify secret is created after merge
   - [ ] Test automated release workflow with dry-run"
   

Step 5c: Add release-lock.yml (Phase 1 — unenforced status check)

This step adds the release-lock commit status workflow to the repo. While the check is not yet required, it reports a green/red status on every PR so the team can observe correct behavior over one or two releases before enforcing it (Phase 2).

What it does: When a version-bump PR (head branch bot/prepare-next-development-iteration-*) is open, all other PRs get a red release-lock status; the bump PR itself gets green. When the bump PR merges, all other open PRs automatically flip back to green — developers do not need to retrigger anything.

The logic lives in a reusable workflow in release-github-actions. Create a thin caller at .github/workflows/release-lock${EXT} (use the same extension detected in Step 1c):

name: Release lock

on:
  pull_request_target:
    types: [opened, reopened, synchronize, closed]

jobs:
  release-lock:
    uses: SonarSource/release-github-actions/.github/workflows/release-lock.yml@v1
    permissions:
      statuses: write
      pull-requests: read

That's the entire file — all logic is in the reusable workflow and updates automatically with @v1.

Stage and commit alongside the automated-release${EXT} file:

git add .github/workflows/release-lock${EXT}

Important: pull_request_target runs with the base branch's code, so the caller above is safe — it does not check out any untrusted PR code. Never add a checkout step to this workflow unless you understand the security implications of pull_request_target.

---

Step 5d: Register release-lock as a required check (Phase 2 — gated, do separately)

⚠️ Do not perform this step in the same skill run as Step 5c. Only run Phase 2 when the team has observed Phase 1 behaving correctly over one or two real releases. Registering a required check without a working reporter blocks all PRs.

When the team is confident, register release-lock as a required status check on the branch. This enforces the gate: while a bump PR is open, all other PRs are blocked from merging.

Prerequisite: The -lock admin Vault token must be available. Its path is development/github/token/{REPO_OWNER_NAME_DASH}-lock (e.g., sonar-apex → development/github/token/sonar-apex-lock). This token already has admin branch-protection write (used by the freeze/unfreeze jobs). Confirm the secret is available before running.

Step 5d-1: Get the current branch protection settings to preserve all existing contexts:

CURRENT=$(gh api "/repos/${REPO}/branches/${BRANCH}/protection" \
  --jq '.required_status_checks.contexts // []')
echo "Current contexts: $CURRENT"

Step 5d-2: Add release-lock to the contexts list and update protection. Use the lock-branch action in a one-shot job or run the Vault-authenticated API call directly (the lock-branch action preserves contexts at lock_branch.py:105-112 — you can also run it as freeze: false to trigger a no-op unfreeze that re-writes the protection and preserves contexts).

The safest approach is to use the GitHub UI:

1. Go to Settings → Branches → Branch protection rules → edit the rule for master (or the release branch).
2. Under Require status checks to pass before merging, search for and add release-lock.
3. Save.

Or via the API (requires admin token):

# Get current contexts
contexts=$(gh api "/repos/${REPO}/branches/${BRANCH}/protection" \
  --jq '[.required_status_checks.contexts[]]')

# Append release-lock and update (one-liner — adjust if contexts is already an array)
gh api --method PUT "/repos/${REPO}/branches/${BRANCH}/protection" \
  --input - <<EOF
{
  "required_status_checks": {
    "strict": false,
    "contexts": $(echo "$contexts" | jq '. + ["release-lock"]')
  },
  "enforce_admins": true,
  "required_pull_request_reviews": null,
  "restrictions": null
}
EOF

Freeze coexistence: Once release-lock is registered, it survives freeze/unfreeze cycles — lock_branch.py (lock_branch.py:105-112) preserves required_status_checks.contexts on every PUT, so the context is never dropped.

---

Step 6: Testing Instructions

Provide these instructions to the user:

1. Test with dry-run first:

   • Go to Actions → Automated Release → Run workflow
   • Set dry-run: true
   • Verify Jira tickets in sandbox, draft PRs, no production artifacts

2. Production release:

   • Set dry-run: false
   • All tickets, releases, and PRs will be created in production

Step 7: Post-Release Checklist

Remind user of post-release tasks:

• Review and merge the bump-version PR (if version bumping was enabled)
• Review and merge the SQS PR in sonar-enterprise
• Review and merge the SQC PR in sonarcloud-core
• Update integration ticket statuses in Jira
• Set fix versions on the SONAR ticket

If SonarQube for IDE integration is enabled:

• Monitor the SLCORE, SLVS, SLVSCODE, SLE, and/or SLI tickets created in Jira
• Coordinate with the relevant SonarQube for IDE teams for integration timelines
• Verify analyzer compatibility with SonarQube for IDE versions

Advanced Options

Mention these optional configurations if relevant:

• Custom artifact names: plugin-artifacts-sqs, plugin-artifacts-sqc
• Custom secret name: release-automation-secret-name
• Disable releasability check: check-releasability: false
• Attach release artifacts: release-artifacts-public, release-artifacts-private — download artifacts from Repox and attach them to the GitHub release draft. Provide full Artifactory paths including the repo name, with {version} as placeholder for the release version.

SonarQube for IDE Integration Details

When SonarQube for IDE integration is enabled, the workflow creates Jira tickets for SLCORE and supported IDEs:

Input	Jira Project	Description
create-slvs-ticket	SLVS	SonarQube for Visual Studio
create-slvscode-ticket	SLVSCODE	SonarQube for VS Code
create-slcore-ticket	SLCORE	SonarLint Core
create-sle-ticket	SLE	SonarQube for Eclipse
create-sli-ticket	SLI	SonarQube for IntelliJ

The sq-ide-short-description input is used as the description for all SonarQube for IDE tickets. This should describe what changes are relevant for these integrations (e.g., "New rules for X", "Updated analysis engine", "Breaking API changes").

When to enable SonarQube for IDE integration:

• The analyzer is used by SonarQube for IDE (standalone analysis)
• New rules or rule changes that affect IDE users
• Breaking changes in the analyzer API
• Performance improvements relevant to IDE analysis

Note: Not all analyzers are integrated with SonarQube for IDE. Check with the relevant SonarQube for IDE teams if unsure whether your analyzer requires integration tickets.

CLI Integration Details

When CLI integration is enabled, the workflow creates a Jira ticket for the CLI scanner team:

Input	Jira Project	Description
create-cli-ticket	CLI	SonarQube CLI scanner

The sq-cli-short-description input is used as the description for the CLI ticket. If not provided, it falls back to short-description. This should describe what changes are relevant for CLI users.

When to enable CLI integration:

• The analyzer is integrated into the SonarQube CLI (ex. sonar-secrets-cli)

References

• Setup Guide: https://github.com/SonarSource/release-github-actions/blob/master/docs/SETUP_AUTOMATED_RELEASE.md
• Workflow Documentation: https://github.com/SonarSource/release-github-actions/blob/master/docs/AUTOMATED_RELEASE.md
• Example: https://github.com/SonarSource/sonar-abap/blob/master/.github/workflows/automated-release.yml