Diego Hernangómez

When GitHub announced [support for
CITATION.cfffiles](https://twitter.com/natfriedman/status/1420122675813441540)
I though ofcreating a package that would assist R developers in this
matter. I was alreadyusing
[codemetar](https://docs.ropensci.org/codemetar/) for most of my
packages,so I was familiar with the creation of these kind of metadata
files.

I borrowed some ideas from codemetar, although I decided to create most
of mycode from scratch (I enjoy challenging myself, and there is no
better way oflearning). Finally, the first working version
of[cffr](https://docs.ropensci.org/cffr/) was released on September 15,
2021.

## The challenge

One of the things I had always in mind is that cffr should be able to
work withany R package, no matter if it was available on CRAN,
Bioconductor, the[R-universe](/r-universe/) or exclusively on
GitHub/GitLab. So when I finishedthe initial version, I needed to test
it with the largest possible number ofpackages.

I started setting up a
[testthat](https://testthat.r-lib.org/)^[1](#fn:1){.footnote-ref
role="doc-noteref"}^ test [in
aseparatefolder](https://github.com/ropensci/cffr/blob/main/tests/testthat/test_ci/test-full_cff.R)
which I ignored in .Rbuildignore. This test was basically
a[loop](https://github.com/ropensci/cffr/blob/6260303668303010c0c90ff381518960299a18f0/tests/testthat/test_ci/test-full_cff.R#L35:L61)over
[all the R packages
installedlocally](https://github.com/ropensci/cffr/blob/6260303668303010c0c90ff381518960299a18f0/tests/testthat/test_ci/test-full_cff.R#L4:L7),where
I created the corresponding `cff` object for each package and
validatedit. Finally, the test created a [small report
inMarkdown](https://github.com/ropensci/cffr/blob/6260303668303010c0c90ff381518960299a18f0/tests/testthat/test_ci/test-full_cff.R#L64:L100)with
the summary of the results.

This setup was fine and worked locally, I just needed to run:

::: {.highlight}
``` {.chroma tabindex="0"}
# Load packagedevtools::load_all() # Run the teststestthat::test_dir("tests/testthat/test_ci")
```
:::

And voilà! The Markdown report was created
in`tests/testthat/test_ci/_snaps/full_cff.md`.

However I was not completely comfortable with this setup. Locally, I
haveinstalled \~200 packages, and it seemed to me like a small sample
(CRAN hostsmore than 18,300 packages), so I needed to enlarge that
sample. Also, I didn'twant to install more packages on my computer just
for testing, so the questionwas: **how do I achieve this?**

## The solution: Continuous Integration (CI)

The alternative approach seemed pretty obvious: using CI with GitHub
Actions. Sobasically I created
[thisworkflow](https://github.com/ropensci/cffr/blob/main/.github/workflows/test-ci.yaml)integrating
the previous script^[2](#fn:2){.footnote-ref role="doc-noteref"}^.

But still there were some open questions, such as: **how do I select
ameaningful sample of R packages?**

### Initial steps

The
action[`r-lib/actions/setup-r-dependencies`](https://github.com/r-lib/actions/tree/master/setup-r-dependencies)was
already included in my workflow, so I started using the
`extra-packages`option to install the tidyverse and tidymodels. I
decided to start with thesetwo packages as they import some of the most
popular R packages. Also, extrapoints for
`r-lib/actions/setup-r-dependencies` as it uses caching for theinstalled
packages, meaning that subsequent deploys would be significantlyfaster.

So it was a good start in my quest to test cffr on a large sample of
packages,but I was still not there...

### Working with CRAN Task Views

Do you know [CRAN Task Views](https://cran.r-project.org/web/views/)?
These areuseful collections of packages classified by relevant topics.
With the[ctv](https://cran.r-project.org/web/packages/ctv/index.html)
package^[3](#fn:3){.footnote-ref role="doc-noteref"}^, it isquite
straightforward to install the packages included in each of those views.
Idecided then to install the core packages of all views, in order to
increase mypackage sample:

::: {.highlight}
``` {.chroma tabindex="0"}
# Install core packages of all viewsoptions(repos = c( CRAN = "https://cloud.r-project.org"))allviews <- ctv::available.views()packs <- lapply(seq_len(length(allviews)), function(x) { allviews[[x]]$packagelist})packs <- dplyr::bind_rows(packs)core <- dplyr::filter(packs, core == TRUE)
```
:::

Out of interest, there are a total of **4,276** packages included in the
CRANTask Views (in the `packs` object) and **286** core packages (in the
`core`object).

### Increasing the number with R-universe

[R-universe](/r-universe/) by [Jeroen Ooms](/author/jeroen-ooms/) is a
wonderfulproject that, apart of the functionality of acting as a
CRAN-like repo, includesseveral other components. One of those
components is a specific
[APIEndpoint](https://ropensci.r-universe.dev/ui#api) for every
R-universe with somevery useful resources, such as the ability to
retrieve a [list of all thepackages included in each
R-universe](https://ropensci.r-universe.dev/packages).

This fit perfectly with my needs, so my next step was to retrieve
packages ofselected R-universes:

- [rOpenSci](https://ropensci.r-universe.dev/)

- [r-lib](https://r-lib.r-universe.dev/)

- [R-Forge](https://r-forge.r-universe.dev/)

- [RStudio](https://rstudio.r-universe.dev/)

- [r-spatial](https://r-spatial.r-universe.dev/)

I selected these well-known organizations as they host a lot of popular
packagesamong use**R**s. Also, my hope was that other developers would
have at somepoint checked the DESCRIPTION and the inst/CITATION of many
of these packages asthe starting point for developing their own (as I
usually do 😁), so thesepackages could be considered representative
enough.

Extracting a list of packages from an R-universe is as easy as:

::: {.highlight}
``` {.chroma tabindex="0"}
# rOpenSci packages from R-universeropensci <- unlist(jsonlite::read_json("https://ropensci.r-universe.dev/packages"))ropenscireviewtools <- unlist(jsonlite::read_json("https://ropenscireviewtools.r-universe.dev/packages"))# r-lib packagesrlib <- unlist(jsonlite::read_json("https://r-lib.r-universe.dev/packages"))# R-Forge packagesrforge <- unlist(jsonlite::read_json("https://r-forge.r-universe.dev/packages"))# RStudio packagesrstudio <- unlist(jsonlite::read_json("https://rstudio.r-universe.dev/packages"))# r-spatial packagesrspatial <- unlist(jsonlite::read_json("https://r-spatial.r-universe.dev/packages"))
```
:::

And I joined all the retrieved packages into a single object `all`:

::: {.highlight}
``` {.chroma tabindex="0"}
all <- sort(unique(c(core$name, ropensci, ropenscireviewtools, rlib, rforge, rstudio, rspatial)))
```
:::

That makes a grand total of **925 packages**. At this point, I was quite
happywith the sample, since it included a large set of relevant
packages.

## Final steps: installing the packages

I was almost there! Now, the last step was just to install these
packages andtest them.

With the aim of improving performance, I filtered out the packages
alreadyinstalled on the system like this:

::: {.highlight}
``` {.chroma tabindex="0"}
# Check packages not installed yetinstpack <- as.character(installed.packages()[, "Package"])toinstall <- setdiff(all, instpack)
```
:::

I also decided to install most of the packages directly from CRAN,
except thosebelonging to rOpenSci. For these packages, I decided to use
the R-universeserver, so I would have a mix of CRAN and R-universe
packages in my sample fortesting purposes:

The following script does the trick:

::: {.highlight}
``` {.chroma tabindex="0"}
# Installoptions(repos = c( ropensci = "https://ropensci.r-universe.dev", ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev", CRAN = "https://cloud.r-project.org"))install.packages(toinstall, dependencies = TRUE, verbose = TRUE, quiet = TRUE, type = "binary")# Updateupdate.packages(type = "binary")
```
:::

Note that I installed the packages using `dependencies = TRUE`. This
forces theinstallation of the packages from Depends, Imports and
Suggest, so by doing thisI was substantially increasing the overall
number of packages installed by myGitHub Actions. Thanks to caching, on
a regular run the previous process ofinstalling packages takes less than
4 minutes on GitHub. That, in my opinion, ismore than
satisfactory^[4](#fn:4){.footnote-ref role="doc-noteref"}^.

Then, it was just a matter of running the first chunk presented in this
blogpost as part of the GitHub Actions:

::: {.highlight}
``` {.chroma tabindex="0"}
# Load packagedevtools::load_all() # Run the teststestthat::test_dir("tests/testthat/test_ci")
```
:::

I also created a step (named "Display results") that basically prints
the outputof the Markdown report. The last bits were to include a
scheduled run
via[cron](https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#scheduled-events)and
to use the
action[`actions/upload-artifact@v2`](https://github.com/actions/upload-artifact)
toupdate the final report after each run.

See here an extract of the results of the last run:

::: {.highlight}
``` {.chroma tabindex="0"}
# Test ALL installed packages ## Sessioninfo R version 4.1.2 (2021-11-01) Platform: x86_64-w64-mingw32/x64 (64-bit) Running under: Windows Server x64 (build 17763) Matrix products: default locale: [1] LC_COLLATE=C [2] LC_CTYPE=English_United States.1252 [3] LC_MONETARY=English_United States.1252 [4] LC_NUMERIC=C [5] LC_TIME=English_United States.1252 < omitted > ## Summary [1] "testing a sample of 1930 installed packages" --- ## OK rate [1] "99.74%" --- ## Errors < omitted > ...
```
:::

## The result

At this stage, I was ready to check cffr with a broad number of
packages. Thisworkflow has been really useful for detecting corner cases
not initially coveredin the first release, so after several iterations I
now feel comfortable withthe compatibility of cffr with a large number
of representative R packages.

On subsequent runs (once the packages are cached) the whole workflow run
takes\~13 minutes on Windows and \~8 minutes on macOS. This allows me to
rapidly testany improvement of the package.

## Lessons learned

After validating the metadata of hundreds of packages, there are some
thoughtsthat I would like to share:

1. cffr was able to produce valid `cff` objects for **1,925 packages**
 out of1,930^[5](#fn:5){.footnote-ref role="doc-noteref"}^. I opened
 a couple
 of[pull](https://github.com/selva86/InformationValue/pull/5)[requests](https://github.com/ropensci/photosearcher/pull/13)
 on some of thefailing packages where I saw a clear mistake in the
 metadata. So in someways this exercise could be also used to improve
 other packages by detectingtypos, etc. in the metadata.

2. The DESCRIPTION files are
 [prettystandardized](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file)and
 usually they are not a problem for cffr.
 However,[inst/CITATION](https://cran.r-project.org/doc/manuals/r-release/R-exts.html#CITATION-files)are
 tricky (*Do you have a inst/CITATION? Do you still
 use[`citEntry()`](https://rdrr.io/r/utils/citEntry.html) instead
 of[`bibentry()`](https://rdrr.io/r/utils/bibentry.html)? Maybe you
 use `meta`information from your DESCRIPTION or you
 use[`citation(auto = meta)`](https://rdrr.io/r/utils/citation.html)?*).
 Thiswas the most difficult issue to solve when developing the
 package.

3. There are differences between the accepted keys on `bibentry()`,
 BibTeX
 andthe[`preferred-citation`](https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#preferred-citation)field
 of a CITATION.cff file. I tried to map those as best I
 could,suggestions welcomed!

One thing I did after completing this process was to make use of
the`bibentry()` function instead of `citEntry()` in the inst/CITATION
files of allmy packages. I chose this since the syntax is very similar
to BibTeX, and thefunction also provides guidance on the possible entry
types, as well as specificvalidity checks.

And that's all! If you have any suggestions for how to improve the
currentvalidation workflow, I would be glad to hear it and include it in
my checks.

::: {.footnotes role="doc-endnotes"}

------------------------------------------------------------------------

1. ::: {#fn:1}
 Wickham H (2011). "testthat: Get Started with Testing." *The R
 Journal*,**3**,
 5--10.<https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf>. [↩︎](#fnref:1){.footnote-backref
 role="doc-backlink"}
 :::

2. ::: {#fn:2}
 The workflow is derived
 from[r-lib/actions/tree/master/examples](https://github.com/r-lib/actions/tree/master/examples). [↩︎](#fnref:2){.footnote-backref
 role="doc-backlink"}
 :::

3. ::: {#fn:3}
 Zeileis A (2005). "CRAN Task Views." *R News*, **5**(1), pp.
 39--40.<https://CRAN.R-project.org/doc/Rnews/> [↩︎](#fnref:3){.footnote-backref
 role="doc-backlink"}
 :::

4. ::: {#fn:4}
 Note also the use of `type = "binary"`. The workflow runs on Windows
 andmacOS, so in order to speed up the process I instructed to
 install theprecompiled versions. For that very same reason, I didn't
 run this full teston Linux, since it would be necessary to compile
 every package from source. [↩︎](#fnref:4){.footnote-backref
 role="doc-backlink"}
 :::

5. ::: {#fn:5}
 At the moment of writing, CRAN hosted **18,369 packages**, so the
 testingsample is \~10.5% of the overall number of packages on
 CRAN. [↩︎](#fnref:5){.footnote-backref role="doc-backlink"}
 :::
:::

When GitHub announced support for CITATION.cfffiles I though ofcreating a package that would assist R developers in this matter. I was alreadyusing codemetar for most of my packages,so I was familiar with the creation of these kind of metadata files.

How I Test cffr on (about) 2,000 Packages using GitHub Actions and R-universe

Jeroen Ooms

At rOpenSci, we encourage R package developers to take advantage of
Continuous Integration services to automatically check the package on
different platforms, with different versions of R. The [rOpenSci dev
guide](https://devguide.ropensci.org/ci.html) dedicates chapter 2 to the
topic of *Continuous Integration Best Practices*, and recommends a few
common CI vendors, including [Travis CI](https://travis-ci.com/).

Travis CI has been a pioneer in free public CI services, and made the
concept popular in the open-source community. The service started to get
wide adoption in 2012, and [native support for
R](https://github.com/travis-ci/travis-build/commit/c697bb2240cfc1abb92a95f57d2e72c151104431)
was added by Craig Citro in 2015, with more contributions from [current
maintainers](https://github.com/travis-ci/travis-build/blob/master/lib/travis/build/script/r.rb#L1-L3)
Jim Hester and later Jeroen. In 2016 we wrote a [blog
post](https://ropensci.org/blog/2016/07/12/travis-osx/) about using a
build-matrix in order to check your packages on multiple versions of
Linux and MacOS, which is super powerful for R package development.

![travis-image](https://ropensci.org/assets/blog-images/travis.png)

## A Change of Management

Sadly, good times came to an end. In 2019 the company [was
sold](https://news.ycombinator.com/item?id=18978251) to a private equity
firm, and soon after the acquisition, a large portion of the senior
engineer staff was [layed
off](https://news.ycombinator.com/item?id=19218036). Under the new
management, open-source users started suffering from significant outages
and backlogs, while being pushed towards the new enterprise product
travis-ci.com (the original Travis service was hosted on travis-ci.org).

The big blow came earlier this month, when Travis announced a [new
pricing
model](https://blog.travis-ci.com/2020-11-02-travis-ci-new-billing)
which no longer has a generous free tier for open-source projects, and
also fully [shutting
down](https://mailchi.mp/3d439eeb1098/travis-ciorg-is-moving-to-travis-cicom)
the old travis-ci.org product by December 31. It is still unclear what
exactly the new product will look like, perhaps it can still be useful,
but with the direction the company is heading, we recommend exploring
other options.

## GitHub Actions

Fortunately, there are many other companies offering free CI for
open-source projects these days. Some popular vendors include
[AppVeyor](https://www.appveyor.com/),
[Circle-CI](https://circleci.com/), [Azure
Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/),
and [Gitlab CI](https://docs.gitlab.com/ee/ci/), but the biggest new
player is [GitHub Actions](https://github.com/features/actions): the
native CI/CD system from GitHub.

The GitHub Actions (GHA) platform was introduced only recently, but has
quickly taken over the open-source world. The system is extremely
flexible, allowing you to run any combination of scripts, containers,
and imported actions from other users. The native integration with
GitHub this takes away the annoying authentication dance that is
required for third party services, making the setup completely seamless.
Very generous free build resources are provided for open-source
projects, but if you need something else, GHA also allows you to plug in
[self-hosted
runners](https://docs.github.com/en/free-pro-team@latest/actions/hosting-your-own-runners/about-self-hosted-runners),
giving you complete control of your hardware and build environment.

To get started with GHA for R, the
[r-lib/actions](https://github.com/r-lib/actions) repo has a number of
preconfigured actions and example configurations written by Jim Hester
(again), for installing R, running checks, etc. Simply copy the
[check-standard.yaml](https://github.com/r-lib/actions/blob/master/examples/check-standard.yaml)
file into the `.github/workflows/` folder of your R package
^[1](#fn:1){.footnote-ref role="doc-noteref"}^, then push, and see the
magic happen. Note that Jim's scripts are only one example: GHA will let
you run any script in the OS or container your choice, allowing you to
fully customize what happens on each new push, pull request, opened
issue, etc.

## Thank you Travis !

<figure class="pull-right">
<img src="https://travis-ci.org/images/logos/TravisCI-Mascot-1.png"
width="200" alt="Travis worker" />
</figure>

We will likely only start seeing more of GitHub actions, as it becomes
the default CI for open-source. But for now I would like to thank the
Travis team, especially the initial founders and engineers, for bringing
massive free CI to the open-source ecosystem.

I remember the first time installing Travis on a project, and seeing
commits and pull requests automatically get built and checked, without
having to do anything. I was blown away, it really brought the concept
of pull requests to life. In no time, CI became an integral part of
development, providing an efficient workflow to test new features and
review pull requests, and green badges [started
appearing](https://juliasilge.com/blog/beginners-guide-to-travis/)
everywhere. I think it is fair to say that we could never maintain the
number of projects we do today, if we had to test all those pull
requests manually!

The R community certainly is not alone in this. A user in the
[hackernews](https://news.ycombinator.com/item?id=19218036) discussion
comments:

> Free CI really did provide a massive boost to collaborative
> open-source projects.As a user, it did a lot to increase software
> quality: not just catching inadvertent bugs, but also ensuring that
> there was at least some reproducible way to get the code working, that
> didn't depend on some implicit configuration of the authors system. As
> a maintainer, accepting simple pull requests becomes much easier when
> you can quickly look over the code and check the CI status, and not
> have to try it out locally yourself. It was certainly critical to the
> "social coding" idea behind GitHub.

Of course the open-source community is sad to see Travis become an
enterprise-first product. But in all honesty, the system is no longer
state-of-the-art, and probably won't be able to compete with the new
GitHub/Microsoft products.

Also we are very aware that it is difficult to find a sustainable
business model around open-source, and hope the company will survive by
refocusing on specialized enterprise CI needs. Nevertheless, as we
transition towards a new generation of CI systems, we won't forget the
pioneering role that Travis played in taking open-source collaboration
to the next level. Thank you!

## Migrating your Projects

If you are still using Travis-CI, there are several options. First, you
should convert your `travis-ci.org` account into a `travis-ci.com`
account following
[instructions](https://mailchi.mp/3d439eeb1098/travis-ciorg-is-moving-to-travis-cicom),
if you had not done so already. This will make sure your CI keeps
working after December 31, at least until you run out of credit :-)

As mentioned, we recommend exploring alternatives, in particular GitHub
actions. As things are evolving rapidly, you can keep an eye on the
[r-lib/actions](https://github.com/r-lib/actions) repository, our [dev
guide](https://devguide.ropensci.org/ci.html), and of course have a look
at what other package authors are doing.

Fortunately the vendor lock-in with CI is pretty limited. For standard
configurations you can just replace the `.travis` file with an
equivalent template from another CI service. For customized
configuration, you may have to spend a few minutes translating that to
another format, which is [the price we
pay](http://veekaybee.github.io/2019/02/10/lockin/) for using these
cloud services. Feel free to reach out to the rOpenSci community if you
could use some help!

::: {.footnotes role="doc-endnotes"}

------------------------------------------------------------------------

1. ::: {#fn:1}
 Or automatically with
 [usethis](https://usethis.r-lib.org/reference/use_github_action.html)
 by running:
 `usethis::use_github_action_check_standard()` [↩︎](#fnref:1){.footnote-backref
 role="doc-backlink"}
 :::
:::

At rOpenSci, we encourage R package developers to take advantage of Continuous Integration services to automatically check the package on different platforms, with different versions of R. The rOpenSci dev guide dedicates chapter 2 to the topic of

 Continuous Integration Best Practices

, and recommends a few common CI vendors, including Travis CI. Travis CI has been a pioneer in free public CI services, and made the concept popular in

Moving away from Travis CI

Mathias Göbel

When writing code at some point we want to highlight a specific state,
we want to celebrate reaching a new milestone and usually this is the
moment to prepare a **release**. Nowadays when we all are about to use
`git`{.language-plaintext .highlighter-rouge}, it is quite common to
utilize *tags* for this. A tag points to a specific commit, it is a
persistent shortcut to this point of the development. When using
*git-flow* marking a release is mostly the only use case for *tags*. The
next step is to store a compiled, ready-to-use package -- maybe a Docker
image -- of the software together with a specific tag to bring it all
together: version marker and source code, changelog and release notes
(within the tag description), and of course binary objects, available
via one view that serves as a more verbal and more user friendly history
of the software project.

We are using Gitlab that features all what git offers and many, many,
many more, that's for sure. But releases can be created via API only --
a web interface to this feature is missing. Even worse that there is no
blob (binary large object) store attached to this feature, so the only
alternative is to add URLs to the objects.

"No problemo" the little guy from Melmac would say. There are the build
artifacts we can store attached to the CI (continues integration)
pipeline within Gitlab. But these artifacts have a limited lifetime and
will be deleted after a period configured by the Gitlab administration:
the admins at our computing center. So we do not have a direct chance to
change the configuration here and as of today our artifacts will be
preserved for six days only. Even if we specify a longer period within
the configuration file (`.gitlab-ci.yml`{.language-plaintext
.highlighter-rouge}) like the following example, the administration will
override with a maximum time span: in our case this limit is set to
**six month**.

::: {.language-yaml .highlighter-rouge}
::: {.highlight}
``` highlight
job: artifacts: expire_in: 100 years 
```
:::
:::

Again Gitlab offers the option to preserve certain artifacts. This can
be triggered manually with a button "Keep" at the job details view or
via API.

Lets put this together to get an experience like GitHub users have,
featuring releases in this way and automatize this process within a CI
pipeline. The Requirement: `jq`{.language-plaintext .highlighter-rouge}
(a JSON parser for the command line) and your favorite HTTP client.

Following the recommendation at the Gitlab documentation, we can set up
a job preparing a release and to preserve the artifact. Besides the
availability of `jq`{.language-plaintext .highlighter-rouge} in your
container, it requires access rights to the Gitlab API with the help of
an access token.
[Here](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
are some information about. It is RECOMMENDED to mask this variable, as
it offers access to many features bound to a single personal account. In
addition it can be set to be available only for pipelines triggered form
[protected
branches](https://about.gitlab.com/blog/2014/11/26/keeping-your-code-protected/)
or protected tags. A secret variable named
`GITLAB_TOKEN`{.language-plaintext .highlighter-rouge} will be used in
the following code.

::: {.language-yaml .highlighter-rouge}
::: {.highlight}
``` highlight
# when a git flow release is made, a tag will be pushed starting this job. it # will keep the resulting artifact from the job declared in `JOB_NUMBER_TO_PRESERVE` # and it will set up a Gitlab release at the repo. therefore the merge message starting # at the release branch should be written in markdown, using a backslash as escape character # `\` before `#`. release: stage: deploy only: - tags variables: JOB_NUMBER_TO_PRESERVE: 1 script: # it is also possible to query for a job name by altering the jq filter - 'curl --output jobs.json --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "$CI_API_V4_URL/projects/$CI_PROJECT_ID/pipelines/$CI_PIPELINE_ID/jobs"' - CI_JOB_TARGET=$(jq ".[$((JOB_NUMBER_TO_PRESERVE - 1))].id" < jobs.json) - echo $CI_JOB_TARGET # keep artifact (release will link there) - 'curl --request POST --header "PRIVATE-TOKEN: $GITLAB_TOKEN" "$CI_API_V4_URL/projects/$CI_PROJECT_ID/jobs/$CI_JOB_TARGET/artifacts/keep"' # create release data # parse commit message (markdown, lines starting with “\”) - MARKDOWN=$(echo "$CI_COMMIT_MESSAGE" | sed 's=^\\==g') # prepare the json file - 'jq ".name = \"$CI_PROJECT_PATH $CI_COMMIT_TAG\" | .tag_name = \"$CI_COMMIT_TAG\" | .description = \"$MARKDOWN\" | .assets.links[0].name = \"package\" | .assets.links[0].url = \"https://gitlab.gwdg.de/$CI_PROJECT_PATH/-/jobs/$CI_JOB_TARGET/artifacts/download\" " < gitlab-release.json.tmpl > gitlab-release.json' - 'curl --header "Content-Type: application/json" --header "PRIVATE-TOKEN: $GITLAB_TOKEN" --data @gitlab-release.json --request POST $CI_API_V4_URL/projects/$CI_PROJECT_ID/releases' artifacts: paths: - gitlab-release.json 
```
:::
:::

This pipeline is mostly parameterized and so easy to adapt (or possibly
to be used without any change) in other projects. The job will store the
JSON file used to describe the release as a base to start customizing
the values with the help of `jq`{.language-plaintext
.highlighter-rouge}.

You can see the results in action:+

- [Repo *SADE/assets*](https://gitlab.gwdg.de/SADE/assets/)
- [Gitlab CI pipeline configuration (`gitlab-ci.yml`{.language-plaintext
 .highlighter-rouge})]()
- [Tag](https://gitlab.gwdg.de/SADE/assets/-/tags/v2.1.3)
- [Release](https://gitlab.gwdg.de/SADE/assets/-/releases)
- [build job details (with keept
 artifact)](https://gitlab.gwdg.de/SADE/assets/-/jobs/235028/)
- [release job details(with release data as JSON, manually
 preserved)](https://gitlab.gwdg.de/SADE/assets/-/jobs/235029)

We will enter the release notes directly at
`git flow release finish 'version'`{.language-plaintext
.highlighter-rouge} and put them into the commit message. Commit
Messages are not completely compatible with markdown, even if major web
views will render the commit description in accordance. So we have to
escape the `#`{.language-plaintext .highlighter-rouge} for headlines
with a leasing backslash. The backslash will be removed for the release
description, but unfortunately there is no way to remove it from the
commit description.

When writing code at some point we want to highlight a specific state, we want to celebrate reaching a new milestone and usually this is the moment to prepare a

 release

. Nowadays when we all are about to use git, it is quite common to utilize

 tags

for this. A tag points to a specific commit, it is a persistent shortcut to this point of the development.

Messaggi di Rogue Scholar

How I Test cffr on (about) 2,000 Packages using GitHub Actions and R-universe

Moving away from Travis CI

Gitlab Releases and Blobs