Pivotal Engineering Journal

Technical articles from Pivotal engineers.

How to use "tag_filter" in "git" resources in Concourse CI

How to use “tag_filter” in “git” resources in Concourse CI

Posted on by
Categories:   git    GitHub    Concourse   
Edit this post on GitHub.

Concourse CI offers many different resource types to fetch from and put files into all kind of different places. One of these types is the “git” type, which supports cloning git repositories, or uploading changes.

This blog post will show how this resource type can be used to fetch a specific git tag from the repository.

What are git tags?

git not only knows about branches, which are commonly used to develop new features and later on merge them into the main (or master) branch. It also knows tags, which is a way to specify a descriptive name for a single commit. This is typically used to name versions: every version pointer (tag) will point to a specific commit in the history. That is a very lightweight feature, because the commit is already in the history and the tag is just pointing to it. Not much additional overhead, compared to other SCM.

A list of all available tags in a repository can be extracted using the tag command:

$ git tag

This command allows to use a filter, which understands patterns:

$ git tag -l "*5.8*"

How must the Concourse CI resource be configured?

The resource in CI is specified with a name and type, and in addition the source section becomes an additional tag_filter option:

- name: my_repo
  type: git
  source:
    uri: https://git-server/repos/repo.git
    branch: master
    tag_filter: "release/5.8"

Easy, isn’t it? As with the “git tag” command, a pattern can be used in tag_filter:

- name: my_repo
  type: git
  source:
    uri: https://git-server/repos/repo.git
    branch: master
    tag_filter: "*5.8*"

Pitfalls

Commonly, CI resources are configured in a way that they only load the last n commits:

  - get: my_repo
    params: {depth: 10}

In this case only the last 10 commits are loaded from the repository. The depth option saves bandwidth and disk space. However this also might not load the commit where the tag is pointing to.

If the tag_filter option is used, at least so many commits need to be fetched that the commit where the tag is pointing to is included. A better way is to not use the depth option in such a case, especially if many changes are committed in the repository.