diff --git a/.cursor/cirrus-github-migration.md b/.cursor/cirrus-github-migration.md index c130af09..2b6c7d6c 100644 --- a/.cursor/cirrus-github-migration.md +++ b/.cursor/cirrus-github-migration.md @@ -32,7 +32,7 @@ When updating this migration guide: - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 # Mise Setup - INCLUDES REQUIRED VERSION PARAMETER -- uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 +- uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: version: 2025.7.12 @@ -97,7 +97,7 @@ Update this section when newer versions are released: see [Cirrus-Modules Migration section](#migrating-repositories-using-cirrus-modules) 3. ✅ Check existing `.github/workflows/` for conflicts 4. ✅ Understand the current Cirrus CI configuration patterns -5. ✅ **CRITICAL**: Verify repository visibility (public vs private) - check GitHub repo Settings → General → Repository visibility +5. ✅ **CRITICAL**: Verify repository visibility (public vs private) - Public repos → Use `ubuntu-24.04-large` runners for SonarSource custom actions - Private repos → Use `sonar-xs` runners (recommended) 6. ✅ **SECURITY**: Review third-party actions and pin to commit SHAs @@ -199,7 +199,7 @@ Follow these security principles during migration: ```yaml # ✅ CORRECT - Pinned to commit SHA -- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 +- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 # ❌ WRONG - Unpinned versions - uses: actions/checkout@v4 # Can be modified @@ -258,7 +258,7 @@ maven = "3.9" ### GitHub Workflow Integration ```yaml - - uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 + - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: version: 2025.7.12 ``` @@ -266,7 +266,7 @@ maven = "3.9" **For promote jobs**, disable cache saving: ```yaml -- uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 +- uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: cache_save: false version: 2025.7.12 @@ -276,7 +276,7 @@ maven = "3.9" ### Basic Template -⚠️ **First, check your repository visibility** (Settings → General → Repository visibility) to select the correct runner. +⚠️ **First, check your repository visibility** to select the correct runner. ```yaml name: Build @@ -301,11 +301,10 @@ jobs: id-token: write # Required for Vault OIDC authentication contents: write # Required for repository access and tagging steps: - - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - - uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: version: 2025.7.12 - - uses: SonarSource/ci-github-actions/get-build-number@v1 - uses: SonarSource/ci-github-actions/build-maven@v1 with: deploy-pull-request: true @@ -321,12 +320,11 @@ jobs: id-token: write contents: write steps: - - uses: actions/checkout@v4 - - uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: cache_save: false version: 2025.7.12 - - uses: SonarSource/ci-github-actions/get-build-number@v1 - uses: SonarSource/ci-github-actions/promote@v1 with: promote-pull-request: true @@ -341,21 +339,6 @@ instructions for all custom actions. ### Required Actions for All Projects -#### get-build-number - -Generates unique build numbers stored in GitHub repository properties. **Always include this before build actions**. - -```yaml -- uses: SonarSource/ci-github-actions/get-build-number@v1 -``` - -**Features:** - -- Stores build number in repository property `build_number` -- Sets `BUILD_NUMBER` environment variable and output -- Unique per workflow run ID (unchanged on reruns) -- **Required permissions:** `id-token: write`, `contents: read` - #### promote Promotes builds in JFrog Artifactory and updates GitHub status checks. @@ -379,7 +362,6 @@ Promotes builds in JFrog Artifactory and updates GitHub status checks. with: deploy-pull-request: true # All parameters below are optional with auto-detected defaults - public: false # Auto-detected from repo visibility artifactory-reader-role: private-reader # private-reader/public-reader artifactory-deployer-role: qa-deployer # qa-deployer/public-deployer maven-local-repository-path: .m2/repository # Maven cache path @@ -397,9 +379,8 @@ Promotes builds in JFrog Artifactory and updates GitHub status checks. ##### Overriding Artifactory Roles -In some cases, your existing Cirrus CI configuration may use different Artifactory roles than the -automatic detection. For example, a public repository might use `private-reader` and `qa-deployer` -instead of the default `public-reader` and `public-deployer`. +Some public repositories use private Artifactory credentials instead of the default public ones. This is +common when the repository content is public but the project needs access to private Artifactory repositories. ```yaml # Override artifactory roles to match existing Cirrus CI configuration @@ -410,11 +391,46 @@ instead of the default `public-reader` and `public-deployer`. artifactory-deployer-role: qa-deployer # Override default public-deployer ``` -**When to use this**: Check your `.cirrus.yml` file for the vault paths used: +**🔍 Detection Steps - Follow These Exactly**: + +1. **Check repository visibility**: Verify that the repository is public +2. **Examine `.cirrus.yml` for private reader pattern**: + Look for: `VAULT[development/artifactory/token/${CIRRUS_REPO_OWNER}-${CIRRUS_REPO_NAME}-private-reader access_token]` -- `ARTIFACTORY_PRIVATE_USERNAME: vault-${CIRRUS_REPO_OWNER}-${CIRRUS_REPO_NAME}-private-reader` → Use - `artifactory-reader-role: private-reader` -- `ARTIFACTORY_DEPLOY_USERNAME: vault-${CIRRUS_REPO_OWNER}-${CIRRUS_REPO_NAME}-qa-deployer` → Use `artifactory-deployer-role: qa-deployer` +3. **Examine `.cirrus.yml` for qa-deployer pattern**: + Look for: `VAULT[development/artifactory/token/${CIRRUS_REPO_OWNER}-${CIRRUS_REPO_NAME}-qa-deployer access_token]` + +**🎯 Decision Matrix**: + +| Repository Type | Reader Pattern Found | Deployer Pattern Found | Action Required | +|----------------|---------------------|------------------------|-----------------| +| **Public** | ✅ `private-reader` | ✅ `qa-deployer` | **Override both roles** | +| **Public** | ❌ No pattern | ❌ No pattern | **Use defaults** | +| **Private** | Any pattern | Any pattern | **Use defaults** | + +**🛠️ Implementation Examples**: + +```yaml +# Example 1: Public repo with private artifactory access (OVERRIDE NEEDED) +# Found in .cirrus.yml: ARTIFACTORY_PRIVATE_PASSWORD: VAULT[...private-reader...] +# Found in .cirrus.yml: ARTIFACTORY_DEPLOY_PASSWORD: VAULT[...qa-deployer...] +- uses: SonarSource/ci-github-actions/build-maven@v1 + with: + artifactory-reader-role: private-reader # Override default public-reader + artifactory-deployer-role: qa-deployer # Override default public-deployer + +# Example 2: Public repo with public artifactory access (NO OVERRIDE NEEDED) +# No private-reader or qa-deployer patterns found in .cirrus.yml +- uses: SonarSource/ci-github-actions/build-maven@v1 + with: + # artifactory roles auto-detected (public-reader, public-deployer) + +# Example 3: Private repo (NO OVERRIDE NEEDED) +# Regardless of patterns in .cirrus.yml +- uses: SonarSource/ci-github-actions/build-maven@v1 + with: + # artifactory roles auto-detected (private-reader, qa-deployer) +``` **Available role options:** @@ -523,6 +539,112 @@ instead of the default `public-reader` and `public-deployer`. - **Required permissions:** `id-token: write`, `contents: write` - **Outputs:** `project-version` from package.json, `build-info-url` when deployment occurs +##### Overriding Pull Request Deployment and Promotion + +Certain repositories want to publish PR artifacts to repox and promote them to the `builds` repository from the initial `qa` repository. +This is useful if the project is being tested in another project and you want to reference it from another repository. + +**When to use this**: If your Cirrus CI pipeline has the environment variable `DEPLOY_PULL_REQUEST` set to `true`, you need to configure +these parameters for both the build and promote actions. + +**GitHub Actions Configuration:** + +```yaml +# .github/workflows/build.yml +jobs: + build: + # ... other configuration + steps: + - uses: SonarSource/ci-github-actions/build-maven@v1 + with: + deploy-pull-request: true # Deploy PR artifacts to qa repository + + promote: + # ... other configuration + steps: + - uses: SonarSource/ci-github-actions/promote@v1 + with: + promote-pull-request: true # Promote PR artifacts to builds repository +``` + +**Cirrus CI Equivalent:** + +```yaml +# .cirrus.yml +env: + DEPLOY_PULL_REQUEST: "true" # This triggers both deployment and promotion for PRs +``` + +**Key Points:** + +- **Build Action**: `deploy-pull-request: true` deploys PR artifacts to the `qa` repository +- **Promote Action**: `promote-pull-request: true` promotes PR artifacts from `qa` to `builds` repository +- **Cross-Repository Testing**: Enables other projects to reference PR artifacts for testing +- **Automatic Promotion**: PR artifacts are automatically promoted, not just deployed + +**Migration Steps:** + +1. **Check Cirrus CI**: Look for `DEPLOY_PULL_REQUEST: "true"` in your `.cirrus.yml` +2. **Configure Build Action**: Add `deploy-pull-request: true` to your build action +3. **Configure Promote Action**: Add `promote-pull-request: true` to your promote action + +##### Overriding SonarQube Platform + +The SonarQube platform used for analysis is based on the `SONAR_HOST_URL` in your Cirrus CI configuration. + +**🔍 Detection Steps - Follow These Exactly**: + +1. **Examine `.cirrus.yml` for SONAR_HOST_URL pattern**: + Look for: `SONAR_HOST_URL: VAULT[development/kv/data/... data.url]` + +2. **Check the vault path to determine platform**: + - `development/kv/data/next` → **No action needed** (default platform) + - `development/kv/data/sonarcloud` → Set `sonar-platform: sqc-eu` + - `development/kv/data/sonarqube-us` → Set `sonar-platform: sqc-us` + +**🎯 Decision Matrix**: + +| Vault Path in .cirrus.yml | SONAR_HOST_URL Contains | Action Required | +|----------------------------------------------|-------------------------|-----------------------------------| +| `development/kv/data/next` | `next` | **No override needed** (default) | +| `development/kv/data/sonarcloud` | `sonarcloud` | **Set `sonar-platform: sqc-eu`** | +| `development/kv/data/sonarqube-us` | `sonarqube-us` | **Set `sonar-platform: sqc-us`** | + +**🛠️ Implementation Examples**: + +```yaml +# Example 1: Using sonarcloud platform (EU) +# Found in .cirrus.yml: SONAR_HOST_URL: VAULT[development/kv/data/sonarcloud data.url] +- uses: SonarSource/ci-github-actions/build-maven@v1 + with: + sonar-platform: sqc-eu # Override default next platform + +# Example 2: Using sonarqube-us platform (US) +# Found in .cirrus.yml: SONAR_HOST_URL: VAULT[development/kv/data/sonarqube-us data.url] +- uses: SonarSource/ci-github-actions/build-maven@v1 + with: + sonar-platform: sqc-us # Override default next platform + +# Example 3: Using next platform (default) +# Found in .cirrus.yml: SONAR_HOST_URL: VAULT[development/kv/data/next data.url] +- uses: SonarSource/ci-github-actions/build-maven@v1 + with: + # sonar-platform auto-detected (next) - no override needed +``` + +**Available platform options**: + +- **`next`**: Default SonarQube platform (auto-detected) +- **`sqc-eu`**: SonarCloud EU platform +- **`sqc-us`**: SonarCloud US platform + +**Migration Steps**: + +1. **Check Cirrus CI**: Look for `SONAR_HOST_URL` in your `.cirrus.yml` +2. **Identify vault path**: Determine which vault path is used for the SonarQube URL +3. **Configure platform**: Add `sonar-platform` parameter if needed (see decision matrix above) +4. **Test analysis**: Verify that SonarQube analysis works with the correct platform + ### Additional Actions #### cache @@ -752,8 +874,8 @@ by the custom actions. No need to specify cache folders or cleanup scripts. ```yaml # ✅ Pin third-party actions to commit SHA -- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 -- uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 +- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 +- uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: version: 2025.7.12 @@ -839,9 +961,8 @@ Standard order: 1. `actions/checkout@v4` 2. `jdx/mise-action` (tool setup) -3. `get-build-number@v1` -4. Build action (`build-maven@v1`, etc.) -5. `promote@v1` (promote job only) +3. Build action (`build-maven@v1`, etc.) +4. `promote@v1` (promote job only) ### 7. Avoid Unnecessary Environment Variables @@ -893,8 +1014,21 @@ Only override if you have specific requirements. - [ ] Add standard triggers (push, PR, merge_group, workflow_dispatch) - [ ] Select appropriate runner type (sonar-xs for private repos) - [ ] Configure concurrency control -- [ ] Add checkout, mise, get-build-number steps +- [ ] Add checkout, mise steps - [ ] Add appropriate build action (maven/gradle/poetry) +- [ ] **Verify Overriding Artifactory Roles**: + - [ ] Check repository visibility (public/private) + - [ ] Search `.cirrus.yml` for `private-reader` vault pattern + - [ ] Search `.cirrus.yml` for `qa-deployer` vault pattern + - [ ] If public repo + both patterns found → Add `artifactory-reader-role: private-reader` and `artifactory-deployer-role: qa-deployer` + - [ ] If public repo + no patterns found → Use default auto-detection (no override needed) + - [ ] If private repo → Use default auto-detection (no override needed) +- [ ] Verify Overriding Pull Request Deployment and Promotion +- [ ] **Verify Overriding SonarQube Platform**: + - [ ] Search `.cirrus.yml` for `SONAR_HOST_URL` vault pattern + - [ ] If vault path contains `sonarcloud` → Add `sonar-platform: sqc-eu` + - [ ] If vault path contains `sonarqube-us` → Add `sonar-platform: sqc-us` + - [ ] If vault path contains `next` → Use default auto-detection (no override needed) - [ ] **If using cirrus-modules**: Verify all features are covered by SonarSource custom actions - [ ] Test build job functionality @@ -902,8 +1036,9 @@ Only override if you have specific requirements. - [ ] Add promote job with proper dependencies - [ ] Configure same concurrency control -- [ ] Add checkout, mise (with cache_save: false), get-build-number +- [ ] Add checkout, mise (with cache_save: false) - [ ] Add promote action +- [ ] Verify Overriding Pull Request Deployment and Promotion - [ ] Test promotion functionality ### Phase 4: Additional Workflows @@ -1048,11 +1183,8 @@ some-repository: ## Build Number Configuration -**Critical Step**: After migration, configure the build number in repository settings: - -1. Go to Repository Settings → Custom Properties -2. Set build number to a value **greater than the latest Cirrus CI build** -3. This ensures continuous build numbering after migration +**Critical Step**: After migration, configure the GitHub build number: login to SPEED and run the +[Update GitHub Build Number](https://app.getport.io/self-serve?action=update_github_build_number) action. ## Additional Example Repositories @@ -1087,8 +1219,6 @@ This workflow automatically: ### ✅ DO These -- Get build number before promotion (always include `get-build-number@v1`) -- Move `DEPLOY_PULL_REQUEST` to global environment variable - Use Maven cache key format: `maven-${{ runner.os }}` (better UI filtering) - Include `pr-cleanup.yml` for automatic PR resource cleanup - **SECURITY**: Pin all third-party actions to commit SHA @@ -1119,12 +1249,11 @@ This workflow automatically: ### Common Issues 1. **Missing permissions**: Ensure `id-token: write` and `contents: write` are set -2. **Build numbers**: Always include `get-build-number@v1` before build actions -3. **Tool versions**: Use mise.toml instead of manual setup actions -4. **Cache conflicts**: Use `cache_save: false` in promote jobs -5. **Branch conditions**: Let custom actions handle most conditional logic -6. **Build number continuity**: Set custom property > latest Cirrus CI build -7. **Artifactory role mismatch**: If your Cirrus CI uses different roles than auto-detected, override them: +2. **Tool versions**: Use mise.toml instead of manual setup actions +3. **Cache conflicts**: Use `cache_save: false` in promote jobs +4. **Branch conditions**: Let custom actions handle most conditional logic +5. **Build number continuity**: Set custom property > latest Cirrus CI build +6. **Artifactory role mismatch**: If your Cirrus CI uses different roles than auto-detected, override them: ```yaml # Check .cirrus.yml for actual roles used and override if needed - uses: SonarSource/ci-github-actions/build-maven@v1 @@ -1132,10 +1261,10 @@ This workflow automatically: artifactory-reader-role: private-reader # Match Cirrus CI config artifactory-deployer-role: qa-deployer # Match Cirrus CI config ``` -8. **Cirrus-modules migration**: If migrating from cirrus-modules, don't try to recreate individual features +7. **Cirrus-modules migration**: If migrating from cirrus-modules, don't try to recreate individual features manually - use the comprehensive SonarSource custom actions instead -9. **Security**: Ensure third-party actions are pinned to commit SHA -10. **Script injection**: Never use untrusted input directly in shell commands +8. **Security**: Ensure third-party actions are pinned to commit SHA +9. **Script injection**: Never use untrusted input directly in shell commands ### Security Troubleshooting @@ -1391,11 +1520,10 @@ jobs: id-token: write contents: write steps: - - uses: actions/checkout@v4 - - uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: version: 2025.7.12 - - uses: SonarSource/ci-github-actions/get-build-number@v1 - uses: SonarSource/ci-github-actions/build-maven@v1 with: deploy-pull-request: true @@ -1411,12 +1539,11 @@ jobs: id-token: write contents: write steps: - - uses: actions/checkout@v4 - - uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 with: cache_save: false version: 2025.7.12 - - uses: SonarSource/ci-github-actions/get-build-number@v1 - uses: SonarSource/ci-github-actions/promote@v1 with: promote-pull-request: true @@ -1485,7 +1612,7 @@ maven = "3.9" DEFAULT_BRANCH: ${{ github.event.repository.default_branch }} # ❌ WRONG - GITHUB_TOKEN is already available by default - - uses: jdx/mise-action@bfb9fa0b029db830a8c570757cee683df207a6c5 # v2.4.0 + - uses: jdx/mise-action@c37c93293d6b742fc901e1406b8f764f6fb19dac # v2.4.4 env: GITHUB_TOKEN: ${{ github.token }} # Not needed! ``` @@ -1515,7 +1642,6 @@ maven = "3.9" - Keep it simple - trust the custom actions - Use standard triggers and let actions handle the rest -- Always include `get-build-number@v1` - Use `mise.toml` for tool versions - Let parameters auto-detect from repository settings (public/private, Artifactory roles) - **Leave `.cirrus.yml` unchanged during migration**