Skip to content

Expand builds-and-runs docs to clarify tag behavior across versions #2520

@TC-MO

Description

@TC-MO

Reported on Slack: tag behavior on Actor builds is documented in fragments, with no single place explaining the full picture. Users hit confusing edge cases:

  • Two builds across different versions can share the same tag name (e.g., both 0.0 and 0.1 tagged latest). When the Actor runs, it picks whichever was built last.
  • The auto-tagging dialog reinforces the impression that tags are version-specific, when in practice the effective build for a tag is whichever was built and tagged most recently.

Current docs only state that tags are exclusive across all builds and versions, and that they move when another build is tagged the same.

They do not explain:

  • That tags can be set on builds via the Console UI and via the API (not only at build time).
  • How build numbers are constructed from MAJOR.MINOR by appending .BUILD.
  • That multiple versions can in theory share the same tag, that each new build overrides the tag, and that this is not practical, so different tags should be used for different versions.

Proposed changes

Expand https://docs.apify.com/platform/actors/development/builds-and-runs/builds#tags to:

  1. Document that tags can be set on existing builds through the Console UI and via the API, not only during build creation.
  2. In the Versioning section, explain build number construction (MAJOR.MINOR.BUILD).
  3. Add an explicit note that multiple versions can technically share the same tag, that each build overrides the tag, and that this is not a recommended pattern. Recommend distinct tags per version.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation.t-docsIssues owned by technical writing team.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions