How are tags intended to be used when changing the source of API Specifications?

[Keith Furnell]

Per https://support.atlassian.com/compass/docs/manage-api-specifications/, the source API specification rendered in Compass can be changed to a different repository, path, or default tag using the <> Change source button.

The tool-tip for the Default tag field on the resultant dialog says "This is used to show the API history with a certain tag". Such functionality would seem useful in cases where someone wants to look at a different release of the API than the default branch.

1. However is anyone actually able to either:

• select from a list of tags on the entered repository, or
• enter an arbitrary tag?

For us (using the GitHub for Compass app) the drop-down only presents default and gitbranch:main, and does not allow manual entry of any other tag.

2. Does selection of a non-default tag affect only what the user making the selection see, or all users (i.e. is it user-local or global)?

Related questions:

• https://community.atlassian.com/forums/Compass-questions/API-Specifications-observations/qaq-p/2973546
• https://community.atlassian.com/forums/Compass-questions/Does-the-API-Specifications-page-support-components-with/qaq-p/2994425

[Mia Tamm]

Hi @Keith Furnell,

The Default tag field in Compass is meant to let you point at a specific Git tag or branch (for example, a “v1.2” release) rather than always using your repo’s default branch. In practice, however—especially with the GitHub integration—you only see two options: the unnamed “default” entry and your main branch. You cannot type in or pick any other tags from the repository. And when you save a change here, it updates the component’s API source for everyone, not just your own view.

— Mia Tamm from Simpleasyty

[Keith Furnell]

Thanks for the confirmation. Seems like this is one of those areas of half-finished functionality (at least with the GitHub integration) 🤨