🆕 Public beta: Protected tags

[emmaviolet]

Public beta: Protected tags

👋 We currently have some APIs that will allow repo admins to protect tags on their repos. Details of how this works below!

Related
#5529
https://github.community/t/feature-request-protected-tags/1742
isaacs/github#1091

What we've built

Our beta tag protection feature gives repo admins the option to protect tags on their repo. If they choose to do so, only maintainers and admins will be able to create these tags, and only admins will be able to modify or delete these tags. Tags are protected by patterns - you could protect all tags by using the “*” pattern, but you don’t have to.

To set up and manage these tag protections, we’ve introduced three endpoints, which any repo admin should be able to use:

GET /repos/{owner/{repo}/tags/protection

Returns a list of tag protection rules.

POST /repos/{owner}/{repo}/tags/protection

Creates a new tag protection rule. Payload must include a pattern - example:

curl -" "Authorization: token $GITHUB_TOK"N"
-XPOST -d '{"pattern": "*"}'
https://api.github.com/repos/JasonEtco/testing/tags/protection

{
"id": 123456,
"pattern": "*",
"created_at": "2022-01-12T12:01:47.094-05:00",
"updated_at": "2022-01-12T12:01:47.094-05:00"
}

DELETE /repos/{owner}/{repo}/tags/protection/{tag_protection_id}

Deletes a tag protection rule.

[mathomp4]

Query: What is used for pattern matching? For example, I'd like to protect SemVer tags (vX.Y.Z.T), but I didn't know if the official SemVer regexes work with the parser GitHub uses. I could do v* but then that means verycooltag is protected along with v2.0.0.

I mean, I'll be testing it out, but you might reply faster than I'll be able to test. 😄

[mathomp4]

Well, I think I answered my own question. It handles neither:

❯ gh api /repos/GEOS-ESM/tagprotect/tags/protection -f pattern='^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
{
gh: Bad Request (HTTP 400)
  "message": "Bad Request",
  "documentation_url": "https://docs.github.com/rest/reference/repos#create-tag-protection-state-for-a-repository"
}
❯ gh api /repos/GEOS-ESM/tagprotect/tags/protection -f pattern='^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$'
gh: Bad Request (HTTP 400)
{
  "message": "Bad Request",
  "documentation_url": "https://docs.github.com/rest/reference/repos#create-tag-protection-state-for-a-repository"
}

but does like a simple pattern:

❯ gh api /repos/GEOS-ESM/tagprotect/tags/protection -f pattern='v*'
{
  "id": 21,
  "pattern": "v*",
  "created_at": "2022-02-02T13:16:38.824-05:00",
  "updated_at": "2022-02-02T13:16:38.824-05:00"
}

Hmm. Okay. maybe time to find a less fancy regex...

[emmaviolet]

We're currently using glob-style pattern matching for safety reasons & consistency with branch protection (where we do the same).

[kaumbakahuma]

Private is beta and is protected tags.

[mark-vanderpol-tfs]

Any more information about the pattern expressions possible to match tags? The glob-style is cumbersome to use to handle say v\d+.\d+.\d+(-RC\d+) which is supposed to recognize v2.12.09 and v2.12.10-RC01 (etc)
I am using a few glob rules ( v[0-9].[0-9].* and v[0-9].[0-9][0-9].* ) now to prevent/warn for the creation of tags that start like that, but it's not exhaustive. (Eg would allow v02.09.1-RC-not-valid)

[ctomc]

Hey @emmaviolet I would like to try this new feature for "globalid" organization.
On top of my head I it would also be nice to have an option to extend protected tags to the deployment environments so we could be able to deploy to certain environment only from protected tags (as is currently possible for protected branches)

[emmaviolet]

Enabled for you! And thank you for the feedback. Just so I'm clear, how do you currently do this for protected branches? Is that the rule Require deployments to succeed before merging?

[varunkuar8789]

Hold effective from anywhere

[brettdh]

@emmaviolet this is great to see - I'd love to have it enabled for my user, as well as the "theliturgists" organization.

[kaumbakahuma]

Yes there's a big great to have done.

[joaorosado]

Hi @emmaviolet

Awesome to see this being added.
Long time needed since we are using tags to automatically triggers build releases and there is no easy way to prevent users with Write from triggering them.

Can you please enable it for "OutSystems" organization? (no need for my user)
Thanks

[vedantmgoyal9]

I want to get it enabled for me.

[kaumbakahuma]

Is ok

[loris-cr]

Hi @emmaviolet , if possible please enable this feature for the 'chartrequest' organization, as we're using tags to trigger production builds

[mathomp4]

@emmaviolet I can think of a possible use case that might be nice, though it might not be possible to support. It would be nice if certain tag patterns could only be pushed by certain users. In some of my repos, there are semi-official tags that aren't "final" SemVer tags, but are pretty important and we'd prefer not to have those overwritten.

I know I could give that user Maintainer status but with that does come a lot of extra power...

[emmaviolet]

We're working on this too @mathomp4! Should be enabled soon

[joaorosado]

Nice :)

I was just testing this feature (Thanks for enabling it btw) and also got the same issue on some repositories.
The current scenario is:

• Team 1 is Admin of the repo, are code owners in the main branch and do releases with v2.* tags.
• Team 2 has only Write permissions in the repo, are code owners of a release1 branch, have a branch protection rule to allow them to push to the release1 branch and do releases with v1.* tags

I wanted to apply to the tags the same thing, allow Team 2 to be able to create the v1.* tags without making them repository level maintainers.

[mathomp4]

@joaorosado Interesting. I hadn't thought of that use case, but that is smart. I suppose I should always think "Team" instead of "Person" in GitHub land as well.

[galargh]

Hi @emmaviolet 🎉 It's great news 🚀 I want to use protected tags to protect against accidental Go module releases in orgs I'm a member of. Would you mind enabling it for the following orgs?

• galorgh
• protocol
• ipfs
• ipfs-shipyard
• libp2p
• ipld
• multiformats
• filecoin-project
• filecoin-shipyard

[0xDing]

Hey @emmaviolet I would like to try this new feature for "@brickdoc" organization.

[duboisf]

Could you please enable this feature for the @Flatbook org?

[emmaviolet]

Enabled for all requestors now. Thanks, all!

[vedantmgoyal9]

How do I check? Please tell 🙏🏻

[emmaviolet]

If you try calling those APIs with the PAT token for any repo admin, it should work.

[vedantmgoyal9]

Thanks!!!

[varunkuar8789]

Give great presentations

[joshua]

@emmaviolet Can you please enable for the @acst org as well? Thanks!

[emmaviolet]

done!

[joshua]

Awesome, Thanks!

[mdragilev]

@emmaviolet can you please enable it for [name-redacted] org as well. Thank you.

[emmaviolet]

done!

[mdragilev]

Thank you!

[hello-smile6]

@mdragilev Your org name is still public, you didn't delete the history.

[ghost]

@emmaviolet could you pls enable it for my org @MorphosisApps . Thank you.

[tedchang77]

@emmaviolet can you please enable for https://github.com/telus-health. thanks!

[tremblaysimon]

@emmaviolet Hello, only a simple feedback from my team. Currently the feature is working as expected but I think there is something missing about Deploy Keys with writing access that can't create/delete tags when protected tags are enabled. Currently the error is "protected tag hook declined" - even if the deploy key used has write access. What I understand it should work like branch protection and Deploy keys has the same admin permissions when they have write access. Ref.: https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys

[twuyts]

One of the steps in a github action is this:

      - env:
          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          tag="${{ steps.bump-semver.outputs.new_version }}"
          git tag "${tag}"
          git push origin "${tag}"

where generate-token generates a PAT for the github-app that has access to this repo and has read/write permission to the contents.

However, the step fails with

remote: error: GH006: Protected tag update failed for refs/tags/v3.0.0.        
remote: error: You're not authorized to create a tag        
To https://github.com/Klarrio/myrepo
 ! [remote rejected] v3.0.0 -> v3.0.0 (protected tag hook declined)

The tag protection rule is a simple v*, so v3.0.0 should be allowed.

this looks like the exact problem described by @tremblaysimon. Are we missing a permission somewhere? Or is this a bug?

[ctoestreich]

This appears to still be an issue where our action is given admin rights but still can't create a new tag due to tag protection * on the repo.

[SharpEdgeMarshall]

Workaround https://github.com/orgs/community/discussions/10906#discussioncomment-8717893

[jonapgartwohat]

Getting an error from an action (https://github.com/mathieudutour/github-tag-action) when it attempts to write a protected tag.

Error: Reference update failed

When I removed tag protection the action succeeded.

[fractiunate]

This! saved me so much time. We should reach out to maintainer of (https://github.com/mathieudutour/github-tag-action)

[tremblaysimon]

I think it's a similar problem that I described here on the same discussion: https://github.com/orgs/community/discussions/10906#discussioncomment-2633741

Currently it's not possible by a CI system to create a new tag if there is a policy that doesn't allow it. It's not possible to bypass that policy like protected branches allow.

[cyrilico]

Hi, any plans to make this configurable at the organization level as well, so that it can be enforced for all repositories in it?

[cardonator]

It seems like this feature launched without the ability for the GHA actor to push to protected tags. I want to prevent normal users of the repo from pushing tags in a certain format because it screws up our tag and release job, but I can't have both a tag protection rule and run my tag and release job using the actions actor so I can't really use this feature.

[weichunnn]

@emmaviolet wanted to bump this up to know if there are any updates on this issue :)

[s0undt3ch]

Sorry, another bump as our team just faced this issue recently.

[SharpEdgeMarshall]

Another bump

[patrick-knight]

There are no planned enhancements to protected tags. Repository tag rules are the where future work will happen in this space. Specifically, on allowing GHA to bypass rules there are several concerns we have today for allowing that from a security standpoint. Rules do allow bypass via Apps, in addition to roles and teams, which would be the current recommendation.

[SharpEdgeMarshall]

Workaround https://github.com/orgs/community/discussions/10906#discussioncomment-8717893

[sammcj]

As per https://github.com/orgs/community/discussions/31177 being able to protect tags from deletion but not creation and/or the ability to protect a Regex/glob of tags (e.g. v1.0.0 but not v1.0.0-alpha) is really critical for us.

[emmaviolet]

This should be possible - responded on the linked discussion

[L1ghtman2k]

The e.g. v1.0.0 but not v1.0.0-alpha part is not possible AFAIK because full regex is not possible

[datosh]

I use github.ref_protected in my GitHub actions and expected it to evaluate to true when triggered on a protected tag. Sadly, this was not the case.
Might this be a bug? Is there another conditional I can check to see if an action is running on a protected tag?

[gladkikhartem]

@datosh I have exactly the same issue. Probably a bug

[datosh]

Thanks for letting me know @gladkikhartem . Hard to tell if it's a bug since the docs are not explicit about expected behavior.

[datosh]

Could you have a look @emmaviolet , whether this is expected or a bug?

[computnik]

seems like a bug to me too! It limits to using only branches for Environment protection rules for actions!
@emmaviolet thoughts?

[tleerai]

So, am I understanding correctly, there is no way to prevent someone from pushing a tag from an arbitrary branch?

So hypothetically speaking, if I have CICD that fires on every tag push, I can't stop people from making up random branch names and pushing tags?

Or if I just don't want tags to be in the repo for any other reason except when an allowed person creates one?

[emmaviolet]

Apologies, folks, I have been reading along here but haven't managed to get this prioritised yet. Sending over to another team who may be able to assist.

[L1ghtman2k]

For our use case, we would like to require our protected tags for production to be based on protected branches. This would leverage a lot of features offered by protected branches (status checks, reviewers, PRs, etc)

[L1ghtman2k]

It would be also nice to have a dedicated event, that apps can subscribe to, like https://docs.github.com/webhooks-and-events/webhooks/webhook-events-and-payloads#branch_protection_rule.

For our use case we would like our github app to update AWS Assume policy on a role (OIDC), based on protected branches set in the repository.

[patrick-knight]

Hey y'all,

We've introduced the beta of repository rules, which include Tag rulesets, which include most of the feature you loved from branch protections and brought them to tags.

If you're on GitHub enterprise you can also protect tag from the org level for all or some repos. Check it out and let us know what you think.

[dragonx]

I'm not sure if I'm misunderstanding how this feature works or if this is a bug, but it's not working the way I thought it would work after reading the docs.

I've created a protected tag called portal-v*, which I thought would prevent users with "Write" access to the repo from creating tags like portal-v5.0.0-202309060000, which we use to kick off a release on our CI server. I expected only users with "Admin" or "Maintain" permissions to be able to create the tag.

However, a user on our team with "Write" permission was able to create a Release with a name similar to that above, and was able to kick off a release. Am I misunderstanding this feature?

[patrick-knight]

Hard to say exactly what's occurring with out more details, so might be worth opening a support case. But what you are describing is how protected tags function.

It might also worth testing out rulesets for protected tags as that feature is now GA.

[gdamjan-loka]

Is it possible to make a ruleset that only allows tags to be made on commits that are on the main branch?

[patrick-knight]

That is currently not possible. So you would be looking for a way to limit tag creation to only commits that must be reachable from main and no other branches? Just checking as they are typically used to notate specific commits as the branch can be an ephemeral ref.

[GMZwinge]

There may be a permission for protected tag missing from permissions to allow the GITHUB_TOKEN to push protected tag. I tried permissions: write-all and the git push --tags still failed with this error:

remote: error: GH006: Protected tag update failed for refs/tags/v<version>.
remote: error: You're not authorized to create a tag        
To https://github.com/<user>/<repo>
 ! [remote rejected] v<version> -> v<version> (protected tag hook declined)
error: failed to push some refs to 'https://github.com/<user>/<repo>'

[patrick-knight]

Correct, and there are no plans at the moment to allow that. A similar limitation exist for actions and bypassing branch protection rules.

The best way to accomplish this today would be with a GitHub App. GitHub Apps require the Repository administration: write permission to modify a protected tag.

[SharpEdgeMarshall]

Workaround https://github.com/orgs/community/discussions/10906#discussioncomment-8717893

[huxuan]

GitHub Apps require the Repository administration: write permission to modify a protected tag.

Hi @patrick-knight , I tried a GitHub App with the corresponding permission but it does not seem to work. Any ideas to debug?

[huxuan]

It turns out to be a issue with actions/checkout, in short, we should set the persist-credentials: false. For more details, please refer to actions/create-github-app-token#75 (comment)

[SharpEdgeMarshall]

Found a solution to the problem of pushing tags from the CI that involves the usage of a write deploy key and is safe you add the key as a secret to an environment bound to a branch/tag:

      - uses: actions/checkout@v4
        with:
          ssh-key: ${{ secrets.SSH_KEY }} # This is you deploy key 
      - name: Commit Bump
        run: |
          MESSAGE="Release <MY_TAG>"
          git config user.name "${GITHUB_ACTOR}"
          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
          git tag -fa "<MY_TAG>" -m "<MY_MESSAGE>"
          git push --force origin "<MY_TAG>"