Home

How to setup GitHub actions with verify-cmsis-example-action

This page will tell you how to add the verify-cmsis-example-action to your GitHub repository. This assumes your repository can run actions which should be the case unless settings have been explicitly changed. See this page for information of managing your GitHub actions settings for a repository.

Create the workflow

The first step is to create a workflow. Click the Add file button and then the Create new file button. This will take you to an online editor where you can add your action.

GitHub actions need to be in a specific directory so that GitHub knows to run them. This directory is .github/workflows/. If you type .github/workflows/ci.yml into the text box then the directories will automatically be created. If your repository already has a file at .github/workflows/ci.yml then you should choose a different name, it won't matter what the file is called as GitHub will run all actions in the .github/workflows/ directory.

Next you can create the action itself.

This action it very simple, you just need to checkout the branch containing the project you want to verify and then pass it a path to the project. One of the necessary inputs is a GitHub secret. You can request a secret from TODO: TOKEN SERVICE. Details on how to add the secret to the repository will be shown in the next section.

More information about the verify-cmsis-example-action can be found on this page.

Click me for copyable version of the workflow

name: CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
verify-project-action:
name: Verify
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: Arm-Examples/verify-cmsis-example-action@latest
name: Verify
with:
branch: ${{ github.ref }}
project-file: ./path/to/csolution.yml
API_TOKEN: ${{ secrets.API_TOKEN }}

If you want to rename the GitHub artifact then you can use the output-artifact: input with any name you want. By default it is called generated-outputs.

This workflow uses the github.ref context. This will match the git reference of the current branch or pull request. Some information on the various GitHub contexts that can be used in workflows can be found on this page.

Note: If you are using a different branch then you will need to specify it correctly in the workflow file.

More detail on creating GitHub actions can be found on this page.

Adding a secret to repository

Go to the settings page of your repository. If you don't see this tab then you will need to contact the repository owner and ask them to add you as a maintainer of the repository.

Once you have access to the tab then you can click the Secrets and variables dropdown and then the Actions button to take you to the page where you add the secret.

You can add the secret (if it isn't aleady available in the Organisation secrets) by clicking the New repository secret button.

In the Name box you should add the name of the secret. This will make the secret available to use via the secrets.XXXXX context in the workflow files. GitHub is clever and will make sure that the secret is censored in all logs generated by the tool. This will not be the case if you hardcode the secret in a workflow so never refer to the secret directly, only reference it via secrets.XXXXX.

Add the secret itself in the Secret box and click the Add secret button. Make sure the secret is correct as you can't view an exisiting secret. You will be able to replace it though if you made a mistake or need to rotate the secret.

Note: a secret in Repository secrets will take precedence of those in Organisation secrets. If you are unsure as there is an existing secret matching your one, then create it under a different name and make the necessary adjustments in the workflow file from earlier.

Running and viewing the workflow

If everything was done correctly then the workflow should be triggered every time a commit is made to the main branch or a pull request that has been made against main. On a pull request you will see icons that let you know whether the verification was successful or not. If you want to see all the workflow runs then you can click on the Actions tab for your repository.

It should be noted that any logs for GitHub actions will only be kept for 7 days. If you want to change this value then it can be found in the settings for your repository.

Interpretting the output of a failing workflow

There are three cases where a job might fail:

• The job fails because the project is not compliant with CMSIS: In this case, on the summary (main page) of the workflow run there will be a box summarising the errors that were recieved when running the job: More information can be found by in the job logs by clicking the error in the Annotations section of the summary.
• The job fails due to invalid options be supplied to the tool (e.g. no token is provided): In this case the summary may be empty and you will need to look ath the logs. If you see an error where the number is between 400 and 499 then it suggests that the error is on the user side. There should be a message providing some insight to the cause of the issue. If the error is confusing, contact the maintainers of the action.
• The job fails due to external factors: If there is no error summary and when going into the logs you see errors like API call error (500) then there is a problem with the services themselves and you should contact the maintainers of the action.

Adding a badge to your repository

If you want a badge that lets users know whether this CI passes:

Then you can do so by adding the following image link to your README.md:

![CMSIS Compliance](https://img.shields.io/github/actions/workflow/status/<ORGANISATION>/<REPOSITORY>/ci.yml?logo=arm&logoColor=0091bd&label=CMSIS%20Compliance)

Replace <ORGANISATION> and <REPOSITORY> with your GitHub organisation/user and repository respectively.

Note: this requires the repository to be public and will not work on private repositories.