Home

How to setup GitHub actions with publish-cmsis-example

This page will tell you how to add the publish-cmsis-example 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.

Examples that are published via this action will take several hours to be shown on keil.arm.com so be patient.

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 check out 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 publish-cmsis-example can be found on this page.

You can get started quickly by copying the example workflow below:

name: CI

on:
  push:
    branches: [ main ]

jobs:
  publish-project-action:
    name: Publish project
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Arm-Examples/publish-cmsis-example@latest
        name: Publish
        with:
          branch: ${{ github.ref }}
          project-file: ./path/to/csolution.yml
          PUBLISH_API_KEY: ${{ secrets.KEIL_API_TOKEN }}
          CMSIS_API_KEY: ${{ secrets.CMSIS_API_KEY }}

Notes:

• 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.

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

• You use the dry-run input to make sure that a publish doesn't actually occur, this can be useful if you want to check a project would be publishable.

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 existing 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. You probably only want to have the publish occur on pushes to your main branch.

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 received 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 at 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:

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

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.