[Bug]: Create Release workflow violates GitHub release patterns and creates misleading user experience

[SteveKrisjanovsD365]

AL-Go Bug Report: Create Release workflow violates GitHub release patterns and creates misleading user experience

AL-Go version

v8.2

Describe the issue

The "Create release" workflow (CreateRelease.yaml) follows an unconventional and confusing release pattern that violates standard GitHub release workflows. Instead of building current code and creating a release from it, the workflow packages already-built artifacts from a previous CI/CD run into a GitHub release. This creates a misleading user experience and breaks expected release semantics.

Why this is a problem

1. Violates standard release workflow pattern

Standard GitHub release pattern:

1. User triggers "Create release" workflow
2. Workflow checks out current code
3. Workflow builds the code
4. Workflow creates Git tag
5. Workflow creates GitHub release from the tag
6. Workflow attaches build artifacts to the release

AL-Go "Create release" pattern:

1. User triggers "Create release" workflow
2. Workflow does not build anything
3. Workflow fetches artifacts from a previous CI/CD run (possibly from different code/commit)
4. Workflow creates Git tag on current commit (not the commit that built the artifacts)
5. Workflow creates GitHub release
6. Workflow attaches old artifacts (from different commit) to release
7. Workflow optionally creates release branch (after creating release - backwards)
8. Workflow optionally increments version number (after creating release - backwards)

This violates user expectations and creates tag/artifact mismatches.

2. Tag and artifact mismatch

Example scenario:

• Commit A (2 days ago): Developer builds app v1.0.100
• Commit B (1 day ago): Developer fixes critical bug, does NOT run CI/CD
• Commit C (today): Developer triggers "Create release" workflow
  • Inputs: tag=v1.0.100, buildVersion=latest
  • Workflow creates tag v1.0.100 on commit C
  • Workflow attaches artifacts from commit A (2 days old)
  • Release tag points to commit C (which has the bug fix)
  • Release artifacts are from commit A (without the bug fix)

Result: The release is invalid. The tag and artifacts don't match. Users who download the release get old code that doesn't correspond to the tagged commit.

3. "Create release" doesn't create a release from current code

When users click "Create release", they expect to release current code. AL-Go's workflow instead releases old artifacts. This is fundamentally misleading.

User expectation:

• "I want to release the code I just committed"
• Triggers "Create release" workflow
• Expects current code to be built and released

AL-Go actual behavior:

• Workflow finds most recent CI/CD artifacts (could be from any commit)
• Packages those old artifacts
• Tags current commit (mismatch!)
• User believes they released current code, but actually released old code

4. Workflow operations happen in backwards order

The workflow performs operations in the wrong sequence:

Current order (wrong):

1. Create release
2. Create release branch (optional)
3. Increment version number (optional)

Correct order:

1. Increment version number (if requested)
2. Create release branch (if requested)
3. Build code from release branch
4. Create release with fresh build artifacts

Creating the release branch after the release defeats the purpose of release branches. Release branches exist to isolate release code from ongoing development. Creating them after the release is already published makes no sense.

5. Deprecated GitHub API usage

Line 173 in CreateRelease.yaml:

make_latest: 'legacy'

This uses deprecated GitHub API behavior. Modern GitHub releases should use:

• make_latest: true for production releases
• make_latest: false for pre-releases/drafts

The 'legacy' mode exists only for backwards compatibility and should not be used in new workflows.

6. Confusing input parameters

From CreateRelease.yaml lines 10-13:

inputs:
  buildVersion:
    description: Build version to promote to release (default is latest)
    required: false
    default: 'latest'

The phrase "promote to release" suggests this is a promotion workflow, not a release creation workflow. It implies artifacts are being promoted from one environment to another, which is not how GitHub releases work.

Users must understand that:

• buildVersion: latest means "find the most recent CI/CD run and package those artifacts"
• The artifacts may be from a completely different branch/commit/date
• The workflow does not build anything

This is unintuitive and error-prone.

Steps to reproduce

Setup

1. Create AL-Go for GitHub AppSource repository (v8.2)
2. Make initial commit with AL code
3. Trigger CI/CD workflow to build artifacts
4. Create new commit with additional changes (do NOT run CI/CD)

Reproduce tag/artifact mismatch

1. Go to GitHub Actions
2. Trigger "Create release" workflow manually
3. Provide inputs:
   • name: "Release 1.0.0"
   • tag: "v1.0.0"
   • buildVersion: "latest"
   • releaseType: "Release"
4. Wait for workflow to complete
5. Check the created release

Expected:

• Tag v1.0.0 points to current commit (latest code)
• Release artifacts contain builds of current commit (latest code)
• Tag and artifacts match

Actual:

• Tag v1.0.0 points to current commit (latest code)
• Release artifacts are from previous CI/CD run (old code, different commit)
• Tag and artifacts do not match

Reproduce confusing workflow order

1. Trigger "Create release" with:
   • createReleaseBranch: true
   • updateVersionNumber: "+0.1"
2. Observe workflow execution order:
   • CreateRelease job runs first
   • Release is created and published
   • CreateReleaseBranch job runs second
   • Release branch is created after release is public

Expected: Release branch should exist before release is published

Actual: Release branch is created after release is published (backwards)

Expected behavior

Recommended design: Standard release workflow

The "Create release" workflow should follow GitHub's standard release pattern:

name: Create Release
on:
  workflow_dispatch:
    inputs:
      name:
        description: Release name
        required: true
      tag:
        description: Release tag (semver)
        required: true
      releaseType:
        description: Release type
        type: choice
        options:
          - Release
          - Prerelease
          - Draft

jobs:
  CreateRelease:
    runs-on: windows-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # Create release branch first (if needed)
      - name: Create release branch
        run: |
          git checkout -b release/${{ inputs.tag }}
          git push origin release/${{ inputs.tag }}

      # Build code from release branch
      - name: Build
        uses: ./.github/workflows/_BuildALGoProject.yaml
        # ... build all projects

      # Create Git tag
      - name: Create tag
        run: |
          git tag ${{ inputs.tag }}
          git push origin ${{ inputs.tag }}

      # Create GitHub release
      - name: Create release
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.repos.createRelease({
              owner: context.repo.owner,
              repo: context.repo.repo,
              tag_name: '${{ inputs.tag }}',
              name: '${{ inputs.name }}',
              draft: ${{ inputs.releaseType == 'Draft' }},
              prerelease: ${{ inputs.releaseType == 'Prerelease' }},
              make_latest: true  # NOT 'legacy'
            });

      # Upload build artifacts
      - name: Upload artifacts
        # ... upload artifacts that were just built

Key differences from current AL-Go implementation:

1. Builds current code instead of packaging old artifacts
2. Creates release branch first (if requested) instead of after
3. Tags the commit being released instead of arbitrary current commit
4. Uses modern GitHub API (make_latest: true) instead of deprecated 'legacy'
5. Tag and artifacts always match because both come from same build

Alternative: Rename to "Promote Build to Release"

If AL-Go's current design is intentional (packaging previous builds), the workflow should be renamed to reflect its actual behavior:

• Current name: "Create release" (misleading)
• Accurate name: "Promote build to release" or "Package existing build"

And the workflow description should clearly state:

"This workflow packages artifacts from a previous CI/CD run into a GitHub release. It does NOT build new code. Use 'buildVersion' input to select which CI/CD run to package."

Actual behavior

Current workflow execution flow

CreateRelease.yaml workflow:

1. Lines 132-140: DetermineArtifactsForRelease action

   • Queries GitHub Actions for workflow runs
   • Finds artifacts from previous CI/CD run matching buildVersion input
   • Returns artifact download URLs
   • Does not build anything

2. Lines 142-149: CreateReleaseNotes action

   • Generates release notes from Git commits
   • Commits may not match artifact commits (mismatch!)

3. Lines 151-180: Create GitHub release

   • Creates tag on current commit
   • Attaches artifacts from different commit
   • Uses deprecated make_latest: 'legacy'

4. Lines 181-266: UploadArtifacts job

   • Downloads artifacts from previous workflow run
   • Uploads to GitHub release
   • Artifacts are from old commit, tag is on new commit

5. Lines 268-289: CreateReleaseBranch job (optional)

   • Creates release branch after release is published
   • Branch creation happens backwards

6. Lines 291-320: UpdateVersionNumber job (optional)

   • Increments version after release is published
   • Version increment happens backwards

Impact on users

Scenario 1: Accidental release of old code

Timeline:

• Monday: Developer commits feature A, runs CI/CD
• Tuesday: Developer commits critical bug fix, forgets to run CI/CD
• Wednesday: Developer triggers "Create release" → Releases Monday's code without the bug fix
• Customer downloads release, encounters bug that was supposedly fixed
• Team loses customer confidence

Scenario 2: Release branch confusion

Timeline:

• Developer triggers "Create release" with createReleaseBranch: true
• GitHub release is published immediately
• Customers start downloading and deploying
• Release branch is created 5 minutes later (after release is public)
• Developer attempts to make hotfix to release branch
• Realizes release branch was created AFTER release was published
• Release branch doesn't serve its purpose

Scenario 3: Tag/artifact forensics nightmare

Timeline:

• Team releases v1.0.100 using AL-Go workflow
• Customer reports bug in v1.0.100
• Developer checks out tag v1.0.100 to investigate
• Developer cannot reproduce bug
• Developer downloads release artifacts
• Artifacts contain different code than tag
• Developer spends hours debugging mismatch
• Discovers tag and artifacts are from different commits

Additional context

How other CI/CD systems handle releases

GitHub Actions (standard pattern):

• Build, then tag, then release
• Tag and artifacts always match
• Release workflow builds current code

Azure DevOps:

• Build pipeline creates artifacts
• Release pipeline deploys artifacts
• Clear separation: "Build" vs "Release" (AL-Go conflates these)

GitLab CI/CD:

• Build job runs first
• Release job depends on build job
• Release uses artifacts from same pipeline run

AL-Go:

• No build in release workflow
• Packages artifacts from arbitrary previous run
• Tag and artifacts can diverge

Why the current design is problematic for AppSource

AL-Go is designed for AppSource app development. AppSource apps must pass Microsoft validation. The current release workflow creates these problems:

1. Validation mismatch: If developer submits release artifacts to AppSource, but those artifacts don't match the release tag, Microsoft validation may flag inconsistencies

2. Source code requirements: AppSource requires source code matching submitted binaries. If release tag and artifacts don't match, source code won't match either

3. Hotfix challenges: If customer finds bug in released version, developer checks out release tag, fixes bug, but cannot easily create patched release because workflow doesn't build from tags

Suggested fixes

Option 1: Complete redesign (recommended)

Redesign "Create release" workflow to follow standard GitHub release pattern:

1. Build current code
2. Create tag
3. Create release
4. Upload fresh build artifacts

Option 2: Rename and document (minimal fix)

Keep current design but:

1. Rename workflow to "Promote build to release"
2. Add prominent documentation explaining it doesn't build code
3. Add validation to prevent tag/artifact mismatches
4. Fix operation order (create branch BEFORE release, increment version BEFORE release)
5. Replace make_latest: 'legacy' with make_latest: true

Option 3: Hybrid approach

Provide two workflows:

1. "Create release from current code" - builds and releases current commit
2. "Promote build to release" - packages existing artifacts (current AL-Go behavior)

Let users choose appropriate workflow for their scenario.

Related issues

This issue relates to broader AL-Go workflow design concerns:

• Workflow input logging (separate issue)
• False positive SUCCESS reporting (issue [Bug]: Publish To Environment workflow does not log user inputs and reports false success when environments are skipped #2147)
• Workflow name inconsistencies (separate issue)

All stem from AL-Go workflows not following GitHub/industry conventions for CI/CD automation.

[spetersenms]

Hi @SteveKrisjanovsD365, thanks for your concern.

The reason we have this setup is to provide a faster flow for users. By having the release workflow take already created artifacts, you don't have to wait to build code that was already compiled previously.

The workflow already have a check that fails the workflow if your current sha on main is different from the one used for the latest CICD build, so you won't have to worry about releasing old code. This is only overridden if you select the "use ghTokenWorkflow" option on the workflow.

[SteveKrisjanovsD365]

That's where opinions differ.

I'm siding with my agentic findings on this one.

Imho - easier and faster should never override best practices and doing it right.

And from my end, I strictly avoid that "create release branch" prompt.

Maybe Microsoft's workflow design works for some, but not for us.

We don't know what our next version number will be (the minor in our version numbering is YYYYMM of the release date - we use versioning strategy 3) and besides we NEVER increment the version until our UAT epic branch passes all technical and functional tests , and that's when I invoke create release.

I sense this is an opinionated design decision on Microsoft's part (no offence!)

[SteveKrisjanovsD365]

@spetersenms Fair enough on the design rationale, and I appreciate the quick response. My concern at this point isn't really the promote-vs-build debate -- I can live with that. What I can't live with is the SHA guard bypass via ghTokenWorkflow being completely undocumented. If I hadn't filed this issue, I never would have known that option disables the very protection you just cited as the reason this design is safe. Same story with Publish To Environment silently reporting success when no environments matched (#2147), and the intentional leading spaces in workflow names (#2150) -- both cost us real time before we figured out what was happening. These caveats need to be documented clearly in the repo, whether that's settings.md, the workflow YAML comments, or a dedicated troubleshooting doc. I'll also flag that the spaces issue in particular is going to become a recurring pain point as more teams adopt agentic and automated DevOps workflows -- AL-Go simply doesn't scale when managed manually, and programmatic tooling will trip over undocumented naming conventions every time. I've been running an agentic DevOps pilot against AL-Go for less than a week and we've already surfaced several of these edge cases. That's not a criticism of the work -- it's a signal that documentation needs to keep pace with how the tooling is actually being used.

[frottke]

@SteveKrisjanovsD365
We do not even need to get into the problems around agentic workflows.
Issue #2078 was already problematic enough earlier this year.

Since today (januari 14th), when a CI/CD workflow is run, GitHub removed the leading space from the name, as can be seen when retrieving all workflow runs on the https://api.github.com/repos/*name*/*reponame*/actions/runs?... endpoint;