FACILE-RS template for GitHub Actions¶

The FACILE-RS GitHub template allows you to integrate automated FACILE-RS workflows to a repository hosted on GitHub.

Description of the workflow¶

Default workflow¶

On simple commits, this pipeline will by default:

generate a DataCite metadata file in XML format and export it as an artifact.
generate a CFF (Citation File Format) file and export it as an artifact. See .github/github.env if you also want to push the file to the repository.

Release workflow¶

You can trigger a release by creating a pre-release tag on GitHub: this tag must start with pre-v.

The pre-release pipeline will then:

update the CodeMeta file with the version identifier (what is after “pre-” in the tag name) and the current date
create or update the CFF file in the repository
create the release tag starting with v, which will trigger the release pipeline

The release pipeline triggered by the creation of this tag will then:

create a GitHub release integrating the DataCite metadata file

Optional workflows¶

You can optionally trigger releases on RADAR or Zenodo by turning ENABLE_ZENODO or ENABLE_RADAR to true in .github/github.env. See the section Optional release workflows for more information about the configuration of these workflows.

Get started¶

In this section, you will modify the content of your GitHub repository. We advise you to create a new branch before proceeding further, so that you don’t modify the content of your default branch directly:

git checkout -b facile-rs-integration

Merge the template into your repository¶

To get started, merge the files from the template repository into your own project. You can copy the files from the template in your project manually, or use the following git commands inside your local git repository:

git remote add facile-rs-template https://github.com/openCARP-org/FACILE-RS-template.git
git fetch facile-rs-template --tags
# This merges the current main branch of the FACILE-RS template.
# You can also merge a tag corresponding to a specific FACILE-RS version.
git merge --allow-unrelated-histories facile-rs-template/main
git remote remove facile-rs-template

Add a CodeMeta file to your repository¶

In order to use FACILE-RS, you have to add a CodeMeta metadata file to your repository.

You can for example generate a file codemeta.json using the CodeMeta generator and include in the root directory of your repository.

Configure the template¶

Open .github/github.env and configure at least:

PROJECT_NAME: the name of your project
CODEMETA_LOCATION: the location of your CodeMeta metadata file (codemeta.json by default)
CFF_PATH: the location of the CFF file to create or update (CITATION.cff by default)
RELEASE_BRANCH: the branch from which you will create releases (By default, it will be the default branch of your repository)

Note : In particular, if you have switched to a new branch facile-rs-integration as advised in the Get started section, and want to test the release workflow from this branch, you should set RELEASE_BRANCH accordingly.

Run your first pipeline¶

Push the changes to GitHub: a workflow should have been triggered on GitHub, and can be seen from your GitHub repository in the Actions section.

Configure your GitHub project for the release workflow¶

If you want your pipeline to be able to update your repository metadata and trigger releases, some additional configuration has to be done on GitHub.

In the next sections, we present two different configuration options: the first option sets up a configuration where only maintainers and/or owners will be able to push to the release branch and create release tags.

The second option introduces a simpler setup that doesn’t implement any protection against write permissions, which means that any collaborator will be able to push to any branch and to trigger releases. This option is typically only suitable for a repo where all collaborators have full permissions.

Option 1: protect release branch and tags (recommended)¶

With this configuration, we will restrict the creation and modification of release branch and tags, as well as the access to the secrets used in FACILE-RS workflows to the repository maintainers.

Allow GitHub Actions to write to your repository: from your GitHub project, go to Settings > Actions > General, and in the section “Workflow permissions”, select “Read and write permissions”.
Protect your release branch with a ruleset: go to Settings > Rules > Rulesets > New Ruleset > New branch ruleset.
- Choose a name, for example “Release branch”.
- Set enforcement status to “Active”.
- In the Bypass list, add “Deploy keys”, “Repository admin” and “Maintain”.
- In Target branches, add the branch you use for release (typically the default branch of your repository, or the value of RELEASE_BRANCH).
- Mark the following branch rules: Restrict creations, Restrict update, Restrict deletions, Block force pushes.
Protect your release tags with a ruleset: go to Settings > Rules > Rulesets > New Ruleset > New tag ruleset.
- Choose a name, for example “Release tags”.
- Set enforcement status to “Active”.
- In the Bypass list, add “Deploy keys”, “Repository admin” and “Maintain”.
- In Target tags, click on Add target > Include by pattern and add the pattern v*. Then do the same for the pattern pre-v*.
- Mark the following tag rules: Restrict creations, Restrict update, Restrict deletions, Block force pushes.
Create an environment for FACILE-RS secrets:
- go to Settings > Environments > New environment, and create an environment named facile-rs.
- In “Deployment branch and tags”, select “Selected branches and tags” and click on “Add deployment branch or tag rule” to add your release branch (for example main) and the release tags patterns (pre-v* and v*)
- Note: you can add secrets needed by FACILE-RS inside this environment to make them only accessible via the release branch and tags (for example: ZENODO_TOKEN, RADAR_PASSWORD, …).
Create a Deploy key, which will allow GitHub Actions to trigger release workflows:
- Generate a SSH key pair, for example using the command ssh-keygen -t ed25519 -f id_ed25519 -N "" -q -C "" in a Unix shell. This command will generate two files in the current directory: a private key named id_ed25519 and a public key id_ed25519.pub. Be sure never to expose the private key publicly!
- Register the private key as a new secret in your facile-rs environment: go to Settings > Environments > facile-rs and click on “Add environment secret”. Give it the name PRIVATE_KEY and as the value, paste the content of the file ed_25519.
- Register the public key as a Deploy key in your GitHub repository: go to Settings > Deploy keys and click on “Add deploy key”. Choose a title for your deploy key and as a value, paste the content of the file ed_25519.pub. Check the box “Allow write access”.
- You can now delete the files ed_25519 and ed_25519.pub.

Option 2: define permissions at the repository level¶

This option should be used cautiously, as it doesn’t implement any protection mechanisms about who can trigger releases and from which branch.

Allow GitHub Actions to write to your repository: from your GitHub project, go to Settings > Actions > General, and in the section “Workflow permissions”, select “Read and write permissions”.
Create a Deploy key, which will allow GitHub Actions to trigger release workflows:
- Generate a SSH key pair, for example using the command ssh-keygen -t ed25519 -f id_ed25519 -N "" -q -C "" in a Unix shell. This command will generate two files in the current directory: a private key named id_ed25519 and a public key id_ed25519.pub. Be sure never to expose the private key publicly!
- Register the private key as a new secret in your repository: go to Settings > Secrets and variables > Actions and click on “New repository secret”. Give it the name PRIVATE_KEY and as the value, paste the content of the file ed_25519.
- Register the public key as a Deploy key in your GitHub repository: go to Settings > Deploy keys and click on “Add deploy key”. Choose a title for your deploy key and as a value, paste the content of the file ed_25519.pub. Check the box “Allow write access”.
- You can now delete the files ed_25519 and ed_25519.pub.

Trigger a software release¶

After having configured your deploy key, you can trigger a software release: create and push a new pre-release tag on GitHub, starting with pre-v, for example pre-v0.0.1.

To do so from a terminal, go to your git repository, ensure your are on the branch you have defined as the release branch, and run the following commands:

git tag pre-v0.0.1
git push origin pre-v0.0.1

The pre-release workflow should then be triggered, followed by the release workflow, which will create a GitHub release of your software. Workflows can be checked in the “Actions” tab. Releases are available in the “Code” tab, on the right side.

Optional release workflows¶

Enable releases on Zenodo¶

When the Zenodo workflow is enabled, the software releases created by the release workflows will also be uploaded to Zenodo. Once a release has been uploaded, you can log in to Zenodo and review it before it is published.

In order to upload releases on Zenodo when triggering the release workflow, you have to enable the Zenodo workflow in the template and to register a Zenodo Personal access token in GitHub:

Set the variable ENABLE_ZENODO to true in .github/github.env.
Set the ZENODO_URL to https://sandbox.zenodo.org for uploading releases on the Zenodo test environment, or to https://zenodo.org to upload releases on Zenodo.
Create a Personal access token on Zenodo: open the ZENODO_URL in a web browser, log in, go to the Applications settings and create a new personal access token with scope “deposit:write”. Copy the token and save it for the next step.
In your GitHub project, create a new secret at the same place as you created the PRIVATE_KEY secret, name it ZENODO_TOKEN and as a value paste the token created in the previous step.

You can now trigger a new release in your release branch by pushing a pre-release tag:

git tag pre-v0.0.2
git push origin pre-v0.0.2

A GitHub release of your software will be created, and in addition, the release will be associated with a DOI and uploaded to Zenodo. Once the workflow has run, you can log in to Zenodo to review and publish your software release.

Enable releases on RADAR¶

In order to use the RADAR workflow, you have to possess publication credentials on a RADAR instance. When the RADAR workflow is enabled, the software releases created by the release workflows will also be uploaded to RADAR. Once a release has been uploaded, you can log in to RADAR and review it before it is published.

In order to use the RADAR release workflow, you have to enable the workflow and to register some RADAR secrets in GitHub:

Set the variable ENABLE_RADAR to true in .github/github.env.
In your GitHub project, create the following secrets at the same place as you created the PRIVATE_KEY secret:
- RADAR_REDIRECT_URL with the value being a link to a web page of your project or repository
- RADAR_EMAIL with the value being the email address of the data steward for this dataset
- RADAR_WORKSPACE_ID with the value being the ID of your RADAR workspace (see the URL to your workspace with the . followed by the name of your workspace)
- RADAR_URL with the value being the URL to your RADAR instance (talk to your RADAR admin)
- RADAR_CLIENT_ID with the value being your RADAR API client ID (talk to your RADAR admin)
- RADAR_CLIENT_SECRET with the value being your RADAR API secret (talk to your RADAR admin)
- RADAR_USERNAME with the value being your RADAR API user name (talk to your RADAR admin)
- RADAR_PASSWORD with the value being your RADAR API password (talk to your RADAR admin)