How to cut tagged releases from the default repo branch

[FelixBenning]

I am a bit unsure if I understand what this does. So I am going to give an example for a workflow and explain what I expect this is doing. If this is correct you could include this example in your readme (I can create a pull request if you want). If this is false please correct me:

name: publish
on:
  push:
    branches:
        - master
    # the following would create a release on any tag creation not necessarily a tag
    # referring to a commit on master (i.e. tagged commits in branches would cause
    # releases)
    # tags:
    #   - 'v*'

jobs:
  pypi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python 3.8
        uses: actions/setup-python@v1
        with:
          python-version: 3.8
      - name: build package
        run: python setup.py sdist bdist_wheel
      - name: publish to PyPI
        # only create relases from tagged commits to master:
        if: startsWith(github.ref, 'refs/tags')
        uses: pypa/gh-action-pypi-publish@v1.4.1
        with:
          user: __token__ # use pypi token instead of username/password
          password: ${{ secrets.pypi_token }} # use secret from github secrets

and another question: can I somehow restrict tagnames to v* ?

[FelixBenning]

apparently I can not read:
https://packaging.python.org/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/

I am still unsure on how it ensures only tags on master are used. But this cleared a lot of things up

[FelixBenning]

It appears that on.push.branches: [master] is not doing what I want.

I woder if on.release.types: [published] would do what I want

[pradyunsg]

ensures only tags on master are used.

A tag is a reference to a specific reference (like a commit), and is not associated with a branch. This SO answer provides a really good summary of how git branches and tags work.

[webknjaz]

Thanks for the comment, I'm going to post a more complete explanation in the context of how GitHub App triggers work relating to how Git works.

P.S. With discussions we now have threads. So it looks like it'd be better to post something like this as a reply to the thread: #42 (comment).

[FelixBenning]

@pradyunsg I am aware that tags are associated with commits. That is why I used this awkward formulation:

referring to a commit on master (i.e. tagged commits in branches would cause releases)

i.e. wouldn't a trigger on.push.tags: [ 'v*'] be triggered for any tag (including tags in merge request which are not yet merged)? Since they are associated with commits I am not sure how I can ensure that releases are only created from master. I.e. I want to ensure that a release corresponds to a tag on master (i.e. a commit on master which is tagged)

And I am not quite sure how to implement that yet. I mean a simple "on push" would alow anyone to create tons of pull requests which would immediately result in pushes to pypi wouldn't it?

[pradyunsg]

Only folks with push access to a repository can push tags to it. This means, I can push a tag to pip's repository, but if you make a fork and push a tag there, it'll trigger the build over on your fork, which likely won't have the secrets (password/API token etc) to succeed.

Since they are associated with commits I am not sure how I can ensure that releases are only created from master.

You'd need to write logic to abort a build if the tag's commit is not on the branch. There's probably a git + bash mix that makes it possible to detect this.

I'm not sure if/when you would need something like this -- is this a specific concern you're trying to resolve?

[FelixBenning]

@pradyunsg there is no specific concern - but it is not a particularly elegant solution to let pipelines crash if they do not have the permissions. Additionally it also means I have to be careful with tagging commits on branches. I would prefer if pipelines were not even started in that case. What do you think about the "on release" idea?

[FelixBenning]

The on release trigger works best for me. Whenever you create a release with the github ui the pypi upload is automatically triggered.

name: publish
on:
  release:
      types:
          - "published"

jobs:
  pypi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python 3.8
        uses: actions/setup-python@v2.1.2
        with:
          python-version: 3.8
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements.txt
      - name: build package
        run: python setup.py sdist bdist_wheel
      - name: publish to PyPI
        # only create relases from tagged commits to master:
        if: startsWith(github.ref, 'refs/tags')
        uses: pypa/gh-action-pypi-publish@v1.4.1
        with:
          # if no "user:" specified use pypi token instead of username/password
          password: ${{ secrets.pypi_token }} # use secret from github secrets

[FelixBenning]

This way the Workflow also is named after the release name

[webknjaz]

Honestly, this way has the same flaws because hitting a release button is also uncoupled from testing and thus also relies on a human factor heavily. I prefer testing what I'm about to publish and only then publishing it. But so far I only have one project that implements this idea fully (it's still tag-triggered though). Besides, the release creation also creates a Git tag so it's practically the same. I'll try to publish a more complete answer about various considerations to be made.

[webknjaz]

@FelixBenning I tried making my answer more comprehensive and generic: #42 (comment). Let me know what you think!

[FelixBenning]

@webknjaz I still think this is a good solution because it decouples the problem from pypi. As you have argued, matching tags to a branch is quite complicated. So one could separately solve this problem and use the github api to trigger releases with this solution. The pypi publication then piggybacks on this solution. So at this point it is not a pypi problem anymore but a: "how can I couple merges of merge requests with tagging and release creation?"- problem.

And when thinking about this problem I realized: If I do not create tags automatically on merges (which is difficult as you then need an algorithm for naming these tags), you are going to have one additional human action anyway (in addition to the merge of the merge request). So if you have this additional action, you might as well click the release button instead of tagging a commit. What's more the release button has a nicer ui than the tag creation anyway.

But if you actually want to create tags automatically when you merge a pull request, then you can solve this problem separately (but use the release api instead of just creating a tag) and my suggested pypi-release-trigger piggybacks along, as it is then triggered as a direct result.

So in that sense it does what I want in both cases (manual tags/releases and automatic tags/releases). The number of total human actions required is either:

• 1 (only merge request approval -> automatic release/tag creation)
• 2 (merge request approval and manual release/tag creation)

both are acceptable in my opinion. And since you use the release api to create these "release tags", you also have the option to create non-release tags (not sure if that ever becomes useful). Which you need to avoid if you trigger on every tag. (That is why I asked whether it was possible to filter tags and only use v* matching tags)

EDIT (regarding testing): in principle you already had tests running before you approved the merge request (in fact you can force green pipelines for merges I think). So whatever is in main/master is already tested so you can savely create releases from it. But if you are very paranoid you can just let your tests trigger on releases as well and wait with the pypi release until they finish.

[webknjaz]

Yeah, the point about a nicer UI is totally valid. In fact, I've been experimenting with using a GitHub App that would add a Release button to commits via Checks API and then trigger Deployments API on click (deployment events can also be used as triggers) but that didn't go further than private experiments.
I must note that you can also use workflow_dispatch that I mentioned in my answer as a visual UI too (without any need to do API calls).

Regarding automatic publishing on merge, I have a number of suggestions about it. First of all, you could use a pull_request.closed event with an additional check for the merged flag in the event context as a trigger. Although, direct pushes to the main branch would bypass it. Some projects (e.g. hypothesis, of the top of my head) use a clever solution to achieve automatic releases on every single merge. They basically require submitting a special file that has a label about whether the release would be a minor or a patch version bump along with a release note. Then, their bot basically uses this to bump the version automatically (I think it's great because it allows avoiding the human factor of picking a wrong tag name), deletes this file, and does all the necessary tagging, releasing, and pushing updates to the main branch.
Talking about the algorithm for picking a new version, I'd like to point out a different approach — use setuptools-scm. This project builds a version from Git. It basically looks up tags in the tree, if the current commit is not tagged it bases the new version on the most recent tag adding a distance between the current commit and that tagged commit to the dev-marker. This is what I use when I build CI/CD publishing every push to the main branch without actually tagging the intermediate commits.

FWIW the actual solution to this problem really depends on the different needs every project may have.

[webknjaz]

The problem statement

I take it you want to ensure that the tags causing your dist to be published "belong" to the main branch in your repository. This does sound straightforward high-level but the actual implementation may be rather complicated. And here's why.

How stuff works

First of all, there are multiple technical sides to this puzzle. Let's explore each one of them.

Git

In Git, tags are roughly pointers to commits. Branches are also labels on commits. There is absolutely no direct relationship between these two except that they both can be resolved to commit hashes.

So just by knowing a tag name and a branch name, there's zero chance to figure out if that tag "belongs" to a given branch.

It is possible to establish, though, if a commit the tag is associated with belongs to a branch.
A branch name by itself won't give us this information because it's just a label on some commit.
Commits belonging to branches are defined as those that are accessible by following the parent pointers starting from the commit labeled with a given branch.

This means that in order to know if a tag is counted as pointing to something on a branch programmatically, we need a copy of the Git repo tree.

One more thing, when the true merge commits are used, you'll see forks with subpaths in commit-tree graphs. It may come as a surprise but all of the commits that may seem to be belonging to another branch would also belong to the main branch upon merging.

Let's look at this example:

E * <- (branch: main)
  |
D * <- [merge commit -- it has two parents: C and H]
  |\
C * * H
  | * G <- (tag: v1.0.0)
B * * F
  |/
A *

In this graph, commits A, B, C, D, E, F, G and H all belong to branch main. This means that the tag v1.0.0 also "belongs" to main (well, sort of — as I said earlier, it's just a label on the commit G and that commit is what truly belongs to main).

Some projects use release-PRs: they make all necessary final release preparations in a branch their upstream repositories, then create a PR and tag the head of that branch.
At this point, the tag does not "belong" to main and can easily be deleted and re-created if there are problems with the release workflow.
If the tag-triggered CI-build passes, they merge the PR at which point that tag starts "belonging" to the main branch.

Events on the GitHub platform

Whenever something happens on GitHub, like actions performed by users or integrations, they are exposed as events that can be analyzed or reacted upon programmatically. There's Events API and webhooks for this — one can either poll GitHub for what's happened or subscribe for events to be delivered to their server by GitHub.

Now, let's take a look at what various events mean (amongst those related to our current needs):

• create — happens whenever a new tag or a new branch appears in the repo (normally, after the initial Git push of the given ref: when this happens, it'll cause a separate push event too)
• pull_request — happens on manipulations with pull requests; when a PR comes from within the same repo, you'll see duplicate push events (hence possible extra duplicate CI runs) on some action types, otherwise push will be in a fork
• push — happens whenever a branch or a tag is git pushed to a given repo
• release — this one can be caused by using Releases GitHub UI in repos or by hitting an API programmatically; publishing a release causes a tag to be created so this will also cause a pair or separate create+push events additionally
• workflow_dispatch — this event is rather recent; it's a way to trigger a given GitHub Actions workflow from the UI and even specify some custom inputs in a user-defined form

GitHub Actions workflow triggers

GitHub Actions workflows are built on top of GitHub Apps and the idea of subscribing to certain events that GitHub platform emits, including but not limited to the ones I mentioned above, and then firing up whatever scenarios you have defined. One workflow may subscribe to multiple events allowing to reuse the same collection of jobs and steps. You can also make some jobs and steps conditional and use event names and their context information to filter out things you don't want to run in some cases.

Some of the event triggers (push/pull_request) have built-in filtering capabilities like branches/branches-ignore/tags/tags-ignore while others don't (create/workflow_dispatch). Also, those supporting filtering don't really allow combining many filters.

There's many approaches to deciding how to trigger building and publishing automatic releases.
First of all, yes — using the built-in UI for publishing releases and subscribing to release.published is totally legit. As well as using git push for tags that the current version of the PyPA guide I wrote a while back showcases. In the latter case, if you want to sync publishing to PyPI with what's shown in the repo Releases tab, it's possible to use GitHub API or even existing GitHub Actions and have this as a step of the automated workflow.

Although, I think that the best semantically correct event to use for tag-based triggers would be create. It's perfectly distinguishable from push and has a meaning "a tag got created" rather than "some code got pushed". Can be addressed with conditionals like:

if: github.event_name != 'create' || github.ref_type == 'tag'

The last variant of trigger I want to talk about is workflow_dispatch. When you declare it, you also specify various input fields. So what you could do is to have this event with a version field there. Then, you'd trigger it from the GitHub UI with the target version. Your job tasks would first perform testing and build your code with the version you specified, then publish, optionally sync with extra places like GitHub releases or maybe a static website and push a tag (and maybe some extra commits if they were necessary for the release) with that version back to the repo. This is probably the best option where you wouldn't have to second-guess if a commit is on the main branch or not because it'd be a part of an automated workflow that guarantees its creation there.

Oh, and I want to emphasize that you can combine various triggers in order to create an automation that suits your needs best.

Huh?

Yeah, this probably sounds complicated but it is what it is. Based on the above, here's a final advice:

1. If you want to trigger the release by first creating a tag, you may end up releasing what's not been tested at all and to verify that your tag is no the main branch, you'd need a separate step doing some woodoo magic to check this and setting a step-output variable and you'll reuse later for skipping jobs early.
2. I do recommend that your testing setup works as follows:

   [build stage] -> [test stage] -> [publish stage] -> [release sync/tagging]

   with the last stages being conditional. In fact, if you really need to, you could have some flag as a workflow_dispatch input that would make the testing conditional during releases for some cases of urgency.
   I also have an example of the workflow that publishes every commit on the main branch as a dev release. It's quite complicated but maybe somebody could draw some inspiration so here's a link: https://github.com/ansible/pylibssh/blob/2a3a4b2/.github/workflows/build-test-n-publish.yml.
3. Since this sort of thing tends to be quite complicated, I recommend drawing some flow-charts and sequence diagrams for your project's CI/CD in order to figure out what setup works best for you. I didn't mention it earlier but there's also a repository_dispatch event that allows you to send in events with custom data structures attached. This is what you can use if you want to trigger jobs by hitting the API from external systems you may have.

[FelixBenning]

good writeup - I finally understood the difference between push and pull_request 😂 - I am currently mostly working by myself so all the pull_requests where also pushes. So I didn't really see the difference.

I still prefer the on release logic as I explained in a comment on my answer. If you agree after reading that, we could merge this nice documentation/explanation of github actions with that suggestion.

[webknjaz]

@FelixBenning every project's needs/preferences are different. So I wanted to have a more generic explanation of the topic. I'm glad that you've figured out what works for you but it seems like you've raised several related (but still different) questions and so I'm not sure if all the discussions should be merged. I think I'd prefer having good Q&A discussion topics posted and explained separately StackOverflow-style rather than dumped in one place because it may be confusing to the people who may come here searching for specific answers in the future...

It'd be great if you decide to contribute more questions (and maybe answers) that are distinct, though. But please make sure to start separate discussions for each of them so that we could have a great knowledge base one day :)