|
2 | 2 |
|
3 | 3 | This reusable GitHub Actions workflow automates the end-to-end release process across Jira and GitHub, and optionally creates integration tickets and analyzer update PRs. It is designed to be invoked via `workflow_call` from other repositories. |
4 | 4 |
|
| 5 | +> **Quick Setup**: Use the [automated-release-setup Claude Code skill](../skills/automated-release-setup/) to automatically set up this workflow in your repository. The skill will guide you through prerequisites, create the necessary workflow files, and configure vault permissions. |
| 6 | +
|
5 | 7 | ## Description |
6 | 8 |
|
7 | 9 | The workflow orchestrates these steps: |
@@ -139,9 +141,94 @@ jobs: |
139 | 141 | - Each job includes a "Summary" step that writes to `$GITHUB_STEP_SUMMARY` only when `verbose: true`. |
140 | 142 | - Permissions and environments are scoped per job to minimize required privileges. |
141 | 143 |
|
| 144 | +## Setup |
| 145 | + |
| 146 | +To set up this workflow in your repository, you need to complete the following prerequisites and create the necessary workflow files. |
| 147 | + |
| 148 | +### Prerequisites |
| 149 | + |
| 150 | +1. **Jira Configuration**: |
| 151 | + - Add `Jira Tech User GitHub` as Administrator on your Jira project (Project settings → People → Administrator role) |
| 152 | + - For dry-run testing, also add the user to the Jira sandbox: https://sonarsource-sandbox-811.atlassian.net/ |
| 153 | + |
| 154 | +2. **Vault Permissions**: |
| 155 | + - Create a PR in `re-terraform-aws-vault` to add the `release-automation` secret |
| 156 | + - File: `orders/{squad}.yaml` (e.g., `orders/analysis-jvm-squad.yaml`) |
| 157 | + - Add the `release_automation` anchor if not present: |
| 158 | + ```yaml |
| 159 | + release_automation: &release_automation |
| 160 | + suffix: release-automation |
| 161 | + description: access to sonar-enterprise and sonarcloud-core repositories to create PRs to update analyzers |
| 162 | + organization: SonarSource |
| 163 | + permissions: |
| 164 | + contents: write |
| 165 | + pull_requests: write |
| 166 | + ``` |
| 167 | + - Add to your repository's `github.customs` section: |
| 168 | + ```yaml |
| 169 | + - <<: *release_automation |
| 170 | + repositories: [your-repo-name, sonar-enterprise, sonarcloud-core] |
| 171 | + ``` |
| 172 | + - Example PR: https://github.com/SonarSource/re-terraform-aws-vault/pull/8406 |
| 173 | + |
| 174 | +3. **Release Workflow**: |
| 175 | + - Update `release.yml` to support `workflow_dispatch` with inputs: `version`, `releaseId`, `dryRun` |
| 176 | + - Add fallbacks for release events: |
| 177 | + ```yaml |
| 178 | + with: |
| 179 | + version: ${{ inputs.version || github.event.release.tag_name }} |
| 180 | + releaseId: ${{ inputs.releaseId || github.event.release.id }} |
| 181 | + dryRun: ${{ inputs.dryRun == true }} |
| 182 | + ``` |
| 183 | + |
| 184 | +### Required Workflow Files |
| 185 | + |
| 186 | +You need to create two workflow files: |
| 187 | + |
| 188 | +1. **`automated-release.yml`**: Main workflow that calls this reusable workflow |
| 189 | +2. **`bump-versions.yaml`**: Bumps version after release (Maven or Gradle) |
| 190 | + |
| 191 | +See the [Usage](#usage) section for examples, or use the [automated-release-setup skill](../skills/automated-release-setup/) for guided setup. |
| 192 | + |
| 193 | +### SonarLint Integration |
| 194 | + |
| 195 | +When your analyzer is used by SonarLint, you can enable integration ticket creation for IDE teams: |
| 196 | + |
| 197 | +| Input | Jira Project | Description | |
| 198 | +|-------|--------------|-------------| |
| 199 | +| `create-slvs-ticket` | SLVS | SonarLint for Visual Studio | |
| 200 | +| `create-slvscode-ticket` | SLVSCODE | SonarLint for VS Code | |
| 201 | +| `create-sle-ticket` | SLE | SonarLint for Eclipse | |
| 202 | +| `create-sli-ticket` | SLI | SonarLint for IntelliJ | |
| 203 | + |
| 204 | +Use `sq-ide-short-description` to describe changes relevant for IDE integrations. |
| 205 | + |
142 | 206 | ## Troubleshooting |
143 | 207 |
|
144 | 208 | - Ensure the caller repository has appropriate permissions to use this workflow and to write releases and PRs. |
145 | 209 | - Verify that `release-automation-secret-name` exists and grants access for creating analyzer update PRs. If omitted, ensure the default secret (`sonar-{plugin-name}-release-automation`) exists and is configured with the required permissions. |
146 | 210 | - Check job logs if the final summary indicates failure; the per-job logs contain detailed outputs even when `verbose` is disabled. |
147 | 211 | - Ensure the `Jira Tech User GitHub` is an Administrator on the target Jira project; admin rights are required to release the Jira version and to create a new version. |
| 212 | + |
| 213 | +## Testing |
| 214 | + |
| 215 | +1. **Test with dry-run first**: |
| 216 | + - Go to Actions → Automated Release → Run workflow |
| 217 | + - Set `dry-run: true` |
| 218 | + - Verify Jira tickets in sandbox, draft GitHub release, draft PRs |
| 219 | + |
| 220 | +2. **Production release**: |
| 221 | + - Set `dry-run: false` |
| 222 | + - All tickets, releases, and PRs will be created in production |
| 223 | + |
| 224 | +## Post-Release Checklist |
| 225 | + |
| 226 | +- Review and merge the bump-version PR |
| 227 | +- Review and merge the SQS PR in sonar-enterprise |
| 228 | +- Review and merge the SQC PR in sonarcloud-core |
| 229 | +- Update integration ticket statuses in Jira |
| 230 | +- Set fix versions on the SONAR ticket |
| 231 | + |
| 232 | +**If SonarLint integration is enabled:** |
| 233 | +- Monitor the SLVS, SLVSCode, SLE, and/or SLI tickets created in Jira |
| 234 | +- Coordinate with IDE teams for integration timelines |
0 commit comments