document brand icons for verified actions in the marketplace

[jsoref]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#branding

What part(s) of the article would you like to see updated?

1. branding
   • Update introduction to briefly mention the avatar used by default and explain that you can use branding to override this avatar for actions published from user-owned repositories and for unverified actions published from organization-owned repositories.
2. About badges in GitHub Marketplace
   • Update to explain that verified actions always display the organization avatar.
   • Mention that for other actions you can override the default icon by updating the action metadata file and link to branding

Additional information

https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace#about-badges-in-github-marketplace has pictures that show icons that are obviously not listed in https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#branding but there's nothing that explains how this works.

[nguyenalex836]

@jsoref Thanks for opening an issue! I'll get this triaged for review ✨

[felicitymay]

Thanks for raising this interesting question. My assumption is that when an organization publishes an action, it automatically inherits the profile image for that organization (for example, Snyk and Atlassian), but that you can override this default by defining branding.

You can see that the https://github.com/marketplace/actions/snyk-node action, created by someone outside the Snyk organization uses the Feather alert-circle icon and that this is defined in the branding metadata for the action: https://github.com/awshole/snyk-node/blob/13b3b80f6e799f615fb8275464e69f04a7fa7057/action.yml#L4-L5.

In contrast, branding is undefined by this action released by the Snyk organization, see https://github.com/snyk/release-notes-preview/blob/master/action.yaml.

Before we add anything about this to the documentation, I'd like to get this confirmed by a subject matter expert.

[github-actions[bot]]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert :eyes:

[nguyenalex836]

Hi @jsoref 👋

It turns out that we were almost right:

• The default icon is the avatar of the owner of repository associated with the action, so an organization or user avatar.
• You can override the default icon by defining an alternate branding.
• A verified action published by an organization has the organization's avatar, overriding any branding defined in an action.yml file.

We'll update the issue summary to suggest making the following docs changes:

1. branding
   • Update introduction to briefly mention the avatar used by default and explain that you can use branding to override this avatar for actions published from user-owned repositories and for unverified actions published from organization-owned repositories.
2. About badges in GitHub Marketplace
   • Update to explain that verified actions always display the organization avatar.
   • Mention that for other actions you can override the default icon by updating the action metadata file and link to branding

and add the help wanted label, so that you or anyone else may submit a PR to make these changes 💛

[jsoref]

@nguyenalex836: the bot attacked again

[jsoref]

@nguyenalex836 / @felicitymay: I just created a test action without a branding key and it didn't show the owner's icon:

check-spelling-sandbox

[jsoref]

advanced-security/component-detection-dependency-submission-action

branding:
  icon: 'upload-cloud'
  color: 'blue'

The action is listed on the marketplace: Component Detection dependency submission action And appears to be a verified creator.

[nguyenalex836]

@jsoref Hmm, interesting! Let me circle back with our SME and see if they are aware of any recent changes - will return with more info 💛

[isaacmbrown]

Hi @jsoref thanks for your patience, I got a slightly different answer from an SME who went and looked at the code:

• Generally we use the icon defined by branding, assuming it matches a Feather icon.
• If no branding is defined we use a default Play icon.
• Except, some verified authors have agreed a custom icon with GitHub, which we use as a priority for these authors. I don't think there's a reason to mention that in the docs though.

[isaacmbrown]

So it seems like the original problem to solve was:

https://docs.github.com/en/actions/creating-actions/publishing-actions-in-github-marketplace#about-badges-in-github-marketplace has pictures that show icons that are obviously not listed in https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#branding but there's nothing that explains how this works.

The answer is:

some verified authors have agreed a custom icon with GitHub, which we use as a priority for these authors.

Since I don't believe that's a point we should add to the docs, I think we can close this issue. Please feel free to reopen it and open a PR if there's something still to document, @jsoref 🙇

[jsoref]

@isaacmbrown: I want to point out that I can't reopen issues:

My view, and the view of my peers is that if you ask people and get wrong answers and in the end someone has to carefully read the code in order to understand what's actually happening, then you should document it so that people understand the behavior without having to follow that process/risk getting wrong answers.

That said, I don't own this repository, can't reopen issues, and have lots of other issues where github folks don't understand processes and that I could also ask someone to fix.