How to add files to existing GitHub release inside workflow

Understanding GitHub Release Immutability

GitHub treats a Release as a distinct entity tied to a specific Git tag or commit. When you publish a release, it becomes a snapshot of that point in history. The GitHub REST API does not provide an endpoint to "add" assets to an existing release object after its initial creation. Attempting to update the release body or title is possible, but modifying the asset list requires a different strategy.

This design choice prevents race conditions where multiple workers might try to modify the same release simultaneously. It also maintains a clear audit trail for each release version. Therefore, the standard pattern in GitHub Actions workflows is to treat the release as a container that accepts uploads during the build process, rather than a mutable database record.

Fetching the Release ID

To upload a file to an existing release, your workflow first needs to identify which release corresponds to the current run. You typically do this by querying the GitHub API for the release associated with the tag being pushed. If you are triggering on a push event to a specific branch or tag, you can extract the tag name from the environment variables provided by GitHub.

curl --silent \
  -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
  https://api.github.com/repos/${{ github.repository }}/releases/tags/${TAG_NAME} \
  | jq '.id'

The command above uses jq to parse the JSON response and extract the numeric ID of the release. You should store this ID in a workflow output variable so subsequent steps can reference it. If no release exists yet, you may need to create one first using the Create a Release endpoint before proceeding to upload assets.

Uploading Assets via Workflow

Once you have the release ID, you can upload files using the Upload Release Asset endpoint. This endpoint accepts multipart form data containing the binary content of your file. In a GitHub Actions workflow, you can use the http action or a simple curl command within a shell step.

- name: Upload Release Asset
  run: |
    curl --data-binary @${{ github.workspace }}/build/output.zip \
      -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
      -H "Content-Type: application/octet-stream" \
      https://uploads.github.com/repos/${{ github.repository }}/releases/${RELEASE_ID}/assets?name=output.zip

Note the distinction between the releases API endpoint and the uploads endpoint. The upload URL always starts with https://uploads.github.com. This separation allows GitHub to handle large file transfers efficiently without blocking the main API server. Ensure that the filename matches exactly what you expect users to download.

Handling Multiple Files

If you need to add multiple files to the same release, repeat the upload step for each artifact. Each request is independent, so they can run sequentially or in parallel depending on your concurrency settings. Be cautious about naming collisions; if a file with the same name already exists, the upload will fail unless you delete the existing asset first.

Common Pitfalls and Solutions

Developers often encounter issues when managing assets across multiple workflow runs. One common problem is accidentally overwriting previous builds or leaving stale artifacts behind. Unlike local file systems, GitHub Releases do not automatically clean up old files when you upload a new one with the same name.

• Token Permissions: Ensure your GITHUB_TOKEN has sufficient permissions. By default, it usually has contents: write, which is required for creating and updating releases. If you are using a custom PAT, explicitly grant it repo-level access.
• File Paths: Verify that the file path in your @ argument points to the correct location in the runner's workspace. Use absolute paths or relative paths from ${{ github.workspace }} to avoid confusion.
• Idempotency: If your workflow runs multiple times for the same tag, consider deleting the asset before uploading it again. You can list assets using the List Release Assets endpoint and filter by name to find the ID of the existing file to delete.

For more details on managing checksums and file integrity in your pipelines, see GitHub Action: Why is appending checksum after each step to checksums.txt overwriting the file each time?. Understanding how your workflow handles file states is crucial when dealing with release assets.

Verifying the Upload

After running your workflow, always check the release page on GitHub to confirm the new file appears. The UI will show the file size and name. You can also use the API to list assets again and compare the count or names against your expectations. Automated verification steps can be added to your workflow to fail the build if the upload did not succeed.

Frequently Asked Questions

Can I edit the release notes after adding files?

Yes, you can update the release body and title at any time using the Update a Release endpoint. This is separate from the asset upload process and does not affect the immutability of the attached files. Many teams prefer to update the notes last to include links to the newly uploaded assets.

What happens if I upload a file with a duplicate name?

The upload will fail with a 422 Unprocessable Entity error if a file with that exact name already exists in the release. You must either rename the new file or delete the existing asset first using the Delete a Release Asset endpoint. Always handle this error gracefully in your workflow scripts.

Is there a limit to the number of assets per release?

GitHub does not enforce a strict limit on the number of files, but each individual asset is capped at 2 GB. The total storage used by all releases in a repository counts toward your overall storage quota. Large numbers of small assets are generally fine, but very large files may require chunked uploads or alternative distribution methods like CDN.

How do I delete an old asset from a release?

You can delete an asset by calling the Delete a Release Asset endpoint with the specific asset ID. First, list the assets to find the ID of the file you want to remove, then send a DELETE request. This is useful for cleaning up failed builds or replacing outdated binaries before uploading a corrected version.

Can I use third-party actions to manage releases?

Yes, many community actions like softprops/action-gh-release simplify the process by handling both creation and asset uploads in one step. These actions abstract away the raw API calls and provide easier configuration options. However, understanding the underlying API mechanics helps when you need to perform complex operations like appending to existing releases.