{"id":18799796,"url":"https://github.com/arduino-ci/action","last_synced_at":"2026-01-03T07:30:13.163Z","repository":{"id":55033820,"uuid":"317046742","full_name":"Arduino-CI/action","owner":"Arduino-CI","description":"GitHub action to run Arduino CI","archived":false,"fork":false,"pushed_at":"2023-06-08T15:01:05.000Z","size":38,"stargazers_count":17,"open_issues_count":7,"forks_count":3,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-02-03T08:47:56.196Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Arduino-CI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-29T21:30:06.000Z","updated_at":"2025-01-21T12:39:58.000Z","dependencies_parsed_at":"2024-06-21T14:12:51.548Z","dependency_job_id":"4f434ebc-7952-4697-8cd1-a3fd8329fe01","html_url":"https://github.com/Arduino-CI/action","commit_stats":{"total_commits":28,"total_committers":2,"mean_commits":14.0,"dds":0.3214285714285714,"last_synced_commit":"2674f4823db04862cee384017e8dbe6f0c535924"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arduino-CI%2Faction","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arduino-CI%2Faction/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arduino-CI%2Faction/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Arduino-CI%2Faction/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Arduino-CI","download_url":"https://codeload.github.com/Arduino-CI/action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239728801,"owners_count":19687411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T22:16:26.806Z","updated_at":"2026-01-03T07:30:13.120Z","avatar_url":"https://github.com/Arduino-CI.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Arduino-CI GitHub Action\n\nThis repository is for the **GitHub Action** to run [`arduino_ci`](https://github.com/Arduino-CI/arduino_ci) on a repository containing an Arduino library.  You can also run it locally with Docker, _right now_, if that's easier -- see below.\n\n\n## Why You Should Use This Action\n\n- Contributions to your Arduino library are tested automatically, _without_ the need for hardware present\n- Example sketches in your `examples/` directory are compiled automatically, to detect broken code in the default branch\n\n### See Also\n* [`arduino-lint` action](https://github.com/marketplace/actions/arduino-arduino-lint-action) for verifying metadata (e.g. `library.properties`) and structural aspects of a library\n\n## Adding Arduino CI Pull Request Tests To Your Project\n\n1. Create a new YAML file in your repository's `.github/workflows` directory, e.g. `.github/workflows/arduino_ci.yml`\n2. Copy an example workflow from below into that new file, no extra configuration required\n3. Commit that file to a new branch\n4. Open up a pull request and observe the action working\n5. Merge into your default branch to enable testing of all following pull requests\n\n\n### Configuring a Workflow to Use the GitHub Action\n\nThere are several ways to specify what version of the action to run.\n\nValue for `uses:`              | Meaning | Pros | Cons\n-------------------------------|---------|------|------\n`Arduino-CI/action@v0.1.6`     | exact version | Complete control | Adopt new versions manually, which may be tiresome if you have many libraries\n`Arduino-CI/action@latest`     | bleeding-edge unreleased `arduino_ci` version | Receive latest features \u0026 fixes automatically | High risk of encountering breaking changes or new bugs\n`Arduino-CI/action@stable-1.x` | use highest available `arduino_ci` version that is \u003c `2.0.0` | Receive latest features \u0026 fixes automatically, but avoids breaking changes | Not a 100% guarantee against unintended CI changes\n\nUsing `Arduino-CI/action@stable-1.x` is **recommended**, so the contents listed below for `.github/workflows/arduino_ci.yml` should work for most users.\n\n```yml\n---\nname: Arduino_CI\n\non: [pull_request]\n\njobs:\n  arduino_ci:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@v3\n      - uses: Arduino-CI/action@stable-1.x\n```\n\nThe full set of configuration options for the action is enumerated here; note that if the `env:` section is empty, it must be commented out or deleted as well.\n\n```yml\n---\nname: Arduino_CI\n\non: [pull_request]\n\njobs:\n  arduino_ci:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@v3\n      - uses: Arduino-CI/action@stable-1.x   # or latest, or a pinned version\n        env:\n          # Not all libraries are in the root directory of a repository.\n          # Specifying the path of the library here (relative to the root\n          # of the repository) will adjust that.\n          #\n          # The default is the current directory\n          #\n          USE_SUBDIR: .\n\n          # Not all libraries include examples or unit tests.  The default\n          #  behavior of arduino_ci is to assume that \"if the files don't\n          #  exist, then they were not MEANT to exist\".  In other words,\n          #  if you were to accidentally delete all your tests or example\n          #  sketches, then the CI runner would by default assume that was\n          #  intended and return a passing result.\n          #\n          # If you'd rather have the test runner fail the test in the\n          #  absence of either tests or examples, uncommenting either of\n          #  the following variables to 'true' (as appropriate) will\n          #  enforce that.\n          #\n          EXPECT_EXAMPLES: false\n          EXPECT_UNITTESTS: false\n\n          # Although dependencies will be installed automatically via the\n          # library manager, your library under test may require an\n          # unofficial version of a dependency.  In those cases, the custom\n          # libraries must be insalled prior to the test execution; those\n          # installation commands should be placed in a shell script (that\n          # will be executed by /bin/sh) stored in your library.\n          #\n          # Then, set this variable to the path to that file (relative to\n          # the root of your repository).  The script will be run from\n          # within the Arduino libraries directory; you should NOT attempt\n          # to find that directory nor change to it from within the script.\n          #\n          # CUSTOM_INIT_SCRIPT: install_dependencies.sh\n```\n\n### Status Badges\n\nYou can show Arduino CI status with a badge in your repository `README.md`\n\n```markdown\n[![Arduino CI](https://github.com/\u003cOWNER\u003e/\u003cREPOSITORY\u003e/workflows/Arduino_CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)\n```\n\n\u003e Note that\n\u003e * you must replace `\u003cOWNER\u003e` with your GitHub username\n\u003e * you must replace `\u003cREPOSITORY\u003e` with the name of the GitHub repository\n\u003e * `Arduino_CI` in the URL must match the `name: Arduino_CI` line in the example YAML files above\n\n\n## Configuring Behavior of the Arduino CI Test Runner Itself\n\nWhen configuring the test runner itself, it's more efficient to run `arduino_ci` locally -- it works on the same OSes as the Arduino IDE.  Instructions for setting that up can be found at [the `arduino_ci` project homepage on GitHub](https://github.com/Arduino-CI/arduino_ci).  If you are using OSX or Linux, you have the additional option of running Arduino CI directly from Docker -- see below.\n\n\n### Writing Unit Tests\n\nFor information on Arduino unit testing with `arduino_ci`, see the [`REFERENCE.md` for Arduino CI's section on unit testing](https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md#writing-unit-tests-in-test)\n\n\n### Testing Different Arduino Platforms\n\nBy default, any unit tests and example sketches are tested against a modest set of Arduino platforms.  If you have architectures defined in `library.properties`, that will further refine the set of what is tested.  You can further override this configuration in several specific ways; for details, see the [`REFERENCE.md` for Arduino CI's section on CI configuration](https://github.com/Arduino-CI/arduino_ci/blob/master/REFERENCE.md#indirectly-overriding-build-behavior-medium-term-use-and-advanced-options)\n\nThe default configuration is [available in the `arduino_ci` project](https://github.com/Arduino-CI/arduino_ci/blob/master/misc/default.yml), and shows how the platforms and packages are configured (including 3rd-party board provider information).\n\n\n## Immediate Usage / Development Workflow using Docker\n\nThe same Docker image used by the GitHub action is available for local testing, and should function properly on Linux and OSX hosts with [Docker](https://www.docker.com/products/docker-desktop) installed.  Choose the command that best matches the state of your project, and use the `-\n\n\n### Your Arduino Libraries directory has everything set up just right; you just want to get up and running and not worry about dependencies at all\n\nComponent                               |Path\n----------------------------------------|----\nArduino's \"libraries\" directory         | `/pathTo/Arduino/libraries`\nYour library under test, called `mylib` | `/pathTo/Arduino/libraries/mylib`\nA custom library `mylib` depends on     | `/pathTo/Arduino/libraries/custom`\n\n\nIn this situation, you've got a mix of libraries installed locally (the one that will be tested amongst any possible dependencies), and they all work as expected (even though you're not quite sure all of them are up to date, nor whether they have local modifications that aren't part of the official library release).  This setup won't work in CI, but by volume-mounting the libraries directory into the container and using your own library as the working directory, you can ensure that arduino_ci is using the _exact_ same set of dependencies.\n\n\u003e This is also the fastest way to test new versions of dependencies.\n\nYou would run the following (substituting your own library's name in place of `mylib`):\n\n```bash\ndocker run --rm \\\n  -v \"/pathTo/Arduino/libraries:/root/Arduino/libraries\" \\\n  --workdir /root/Arduino/libraries/mylib \\\n  docker.pkg.github.com/arduino-ci/action/ubuntu\n```\n\n\n### Your Arduino Library uses only \"official\" library versions as dependencies\n\nComponent                               |Path\n----------------------------------------|----\nArduino's \"libraries\" directory         | `/pathTo/Arduino/libraries`\nYour library under test, called `mylib` | `/pathTo/Arduino/libraries/mylib`\n\nIn this situation, the only libraries you need for your library to work are those that you've downloaded directly from the library manager and no special modifications need to be made.  We simply volume mount the library under test into the container, set that directory to be the working directory, and let the `arduino_ci` test runner install the dependencies directly.\n\nIf your project does not include a `library.properties` that defines your project's name, you should change `library_under_test` to `mylib`.\n\n```bash\ndocker run --rm \\\n  -v \"/pathTo/Arduino/libraries/mylib:/library_under_test\" \\\n  --workdir /library_under_test \\\n  docker.pkg.github.com/arduino-ci/action/ubuntu\n```\n\n\n### Your Arduino Library uses libraries or versions as dependencies that can't be installed by name from the Arduino library manager (but you wrote a script to install them automatically)\n\nComponent                                |Path\n-----------------------------------------|----\nArduino's \"libraries\" directory          | `/pathTo/Arduino/libraries`\nYour library under test, called `mylib`  | `/pathTo/Arduino/libraries/mylib`\nShell script to install `custom` library | `/pathTo/Arduino/libraries/mylib/install.sh`\nA custom library `mylib` depends on      | `/pathTo/Arduino/libraries/custom`\n\nIn this situation, you have a custom library that can't be installed by the library manager.  Fortunately, you've supplied an `install.sh` script that will download and unpack a library to the current working directory (which Arduino CI's test runner will run from inside the container's Arduino libraries directory).  Note the _relative_ path used for `install.sh`.\n\n```bash\ndocker run --rm \\\n  -v \"/pathTo/Arduino/libraries/mylib:/library_under_test\" \\\n  --workdir /library_under_test \\\n  --env CUSTOM_INIT_SCRIPT=install.sh \\\n  docker.pkg.github.com/arduino-ci/action/ubuntu\n```\n\n\n### Your Arduino Library is a subdirectory of a monorepo, you need libraries or versions as dependencies that can't be installed by name from the Arduino library manager, you wrote a script to install them automatically\n\nComponent                                |Path\n-----------------------------------------|----\nArduino's \"libraries\" directory          | `/pathTo/Arduino/libraries`\nA custom library `mylib` depends on      | `/pathTo/Arduino/libraries/custom`\nYour library under test, called `mylib`  | `/pathTo/Monorepo/mylib`\nShell script to install `custom` library | `/pathTo/Monorepo/mylib/install.sh`\n\n\nAll the bells and whistles.  Note that the relative path of `install.sh` is considered _after_ the `USE_SUBDIR` directory has been applied.\n\n```bash\ndocker run --rm \\\n  -v \"/pathTo/Monorepo:/library_under_test\" \\\n  --workdir /library_under_test \\\n  --env USE_SUBDIR=mylib \\\n  --env CUSTOM_INIT_SCRIPT=install.sh \\\n  docker.pkg.github.com/arduino-ci/action/ubuntu\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farduino-ci%2Faction","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farduino-ci%2Faction","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farduino-ci%2Faction/lists"}