{"id":13995577,"url":"https://github.com/leanprover/lean-action","last_synced_at":"2025-04-08T22:32:02.566Z","repository":{"id":238200806,"uuid":"795738301","full_name":"leanprover/lean-action","owner":"leanprover","description":"GitHub action for standard CI in Lean projects","archived":false,"fork":false,"pushed_at":"2025-03-28T12:19:18.000Z","size":194,"stargazers_count":18,"open_issues_count":7,"forks_count":4,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-04T14:41:43.614Z","etag":null,"topics":["github-actions","lean","lean4"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leanprover.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2024-05-03T23:38:51.000Z","updated_at":"2025-03-28T12:13:18.000Z","dependencies_parsed_at":"2024-05-20T23:58:57.211Z","dependency_job_id":"1b898ca0-5af8-4285-97bd-b10aa537a4a2","html_url":"https://github.com/leanprover/lean-action","commit_stats":null,"previous_names":["leanprover/lean-action"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Flean-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Flean-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Flean-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leanprover%2Flean-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leanprover","download_url":"https://codeload.github.com/leanprover/lean-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247940625,"owners_count":21022016,"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":["github-actions","lean","lean4"],"created_at":"2024-08-09T14:03:29.588Z","updated_at":"2025-04-08T22:32:02.551Z","avatar_url":"https://github.com/leanprover.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# lean-action - CI for Lean Projects\n\nlean-action provides steps to build, test, and lint [Lean](https://github.com/leanprover/lean4) projects on GitHub\n\n## Quick Setup\n\nTo setup `lean-action` to run on pushes and pull request in your repo, create the following `ci.yml` file the `.github/workflows`\n\n```yml\nname: CI\n\non:\n  push:\n    branches: [\"main\"] # replace \"main\" with the default branch\n  pull_request:\n    branches: [\"main\"]\n  workflow_dispatch:\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@v4\n      # uses lean standard action with all default input values\n      - uses: leanprover/lean-action@v1\n```\n\n\u003e [!IMPORTANT]\n`lean-action` is tested on `ubuntu-latest`, `macos-latest`, and `windows-latest` GitHub-hosted runners.\nWe recommend using one of these runners for the best experience,\nhowever if you encounter an issue when using a different runner, please still open an issue.\n\n## Caching `.lake` directory with GitHub's `actions\\cache`\nBy default, `lean-action` uses [`actions\\cache`](https://github.com/actions/cache) to cache the `.lake` directory and speed up builds.\n\n\u003e [!NOTE]\nGitHub caching is distinct from Mathlib caching with `lake exe cache get`\n\n### Cache keys\n`lean-action` uses [cache keys](https://github.com/actions/cache?tab=readme-ov-file#creating-a-cache-key) to save and restore caches.\n\nFirst it uses a primary key,\ncomposed of the runner operating system, the runner architecture (X86, X64, ARM, ARM64), the Lake manifest, and the git commit hash,\nto save/restore caches from an exact git commit.\n\nIf there is no primary key cache hit, `lean-action` uses a fallback key, \ncomposed of the operating system, the architecture, and the Lake manifest but not the git commit hash,\nto restore a cache from a previous commit.\n\n### Troubleshooting problems with caching\nBecause caches are shared across different jobs,\ncaching build files can lead to unexpected behavior and errors.\n\nTo determine if the GitHub cache is causing problems you can disable caching with the `use-github-cache` input.\n```yml\n- uses: leanprover/lean-action@v1\n  with:\n    use-github-cache: false\n```\n\nFor more complex workflows, you may want more control over how the `actions\\cache` caches the build in your workflow,\n(.e.g., modifying the cache key to respect a build matrix)\nyou can wrap `lean/action` with `use-github-cache: false` in your own call to `actions\\cache`.\n\n## Configuring which features `lean-action` runs\n\nMost use cases only require a subset of `lean-action`'s features\nin a specific GitHub workflow.\nAdditionally, you may want to break up usage of `lean-action`\nacross multiple workflows with different triggers,\ne.g., one workflow for PRs and another workflow scheduled by a cron job.\n\nTo support these use cases,\n`lean-action` provides inputs to specify the subset of desired features of `lean-action`.\n\n### Directly specifying a desired feature with specific feature inputs\n\nEach feature of `lean-action` has a corresponding input which users can set to `true` or `false`.\nSpecific feature inputs have the highest precedence\nwhen `lean-action` determines which features to run.\nWhen a feature input is set `lean-action` will always try to run the corresponding step.\nIf `lean-action` is unable to successfully run the step, `lean-action` will fail.\n\n`lean-action` provides the following feature inputs:\n\n- `build`\n- `test`\n- `lint`\n- `check-reservoir-eligibility`\n- `lean4checker`\n\n### Automatic configuration\n\nAfter feature inputs, `lean-action` uses the `auto-config` input\nto determine if it should use the Lake workspace to decide which steps to run automatically.\nWhen `auto-config: true`, `lean-action` will use the Lake workspace to detect targets\nand run the corresponding Lake command.\nWhen `auto-config: false`, `lean-action` will only run features specified directly through specific feature inputs.\nUsers can combine `auto-config` with specific feature inputs to override the automatic configuration of `lean-action`.\n\n`lean-action` can automatically configure the following features:\n\n- `build`\n- `test`\n- `lint`\n\n### Breaking up `lean-action` across workflows\n\nSometimes it is useful to break up usage of `lean-action`\nacross multiple workflows with different triggers,\ne.g., one workflow for PRs and another workflow scheduled by a cron job.\n`auto-config: false` allows users to run only a specific subset of features of `lean-action`.\n\nFor example, run only `lean4checker` in a cron job workflow:\n\n```yaml\n- name: \"run `lean-action` with only `lean4checker: true`\"\n  id: lean-action\n  uses: leanprover/lean-action@v1\n  with:\n    auto-config: false\n    lean4checker: true\n```\n\n### Differences between using `auto-config` and feature inputs\n\nWhen you specify a feature with a feature input, `lean-action` will fail if it can't complete that step.\nHowever, if you use `auto-config`,\n`lean-action` will only fail if it detects a target in the Lake workspace and the detected target fails.\n\nFor example, if the `lakefile.lean` contains an improperly configured `test_driver` target\nand you configure `lean-action` with `test: true`, `lean-action` will fail.\nHowever the same improperly configured `test_driver` may not cause a `lean-action` failure with `auto-config: true`,\nbecause `lean-action` may not detect the `test_driver` in the Lake workspace.\n\nTo be certain `lean-action` runs a step, specify the desire feature with a feature input.\n\n## Customization\n\n`lean-action` provides optional configuration inputs to customize the behavior for your specific workflow.\n\n```yaml\n- uses: leanprover/lean-action@v1\n  with:\n    \n    # Automatically configure `lean-action` based on the Lake workspace.\n    # When set to \"true\", `lean-action` will use the Lake workspace to determine\n    # the set of features to run on the repository, such as `lake build` and `lake test`.\n    # Even when set to \"true\", the user can still override the auto configuration\n    # with the `build` and `test` inputs.\n    # Allowed values: \"true\" or \"false\".\n    # Default: \"true\"\n    auto-config: \"\"\n    \n    # Run `lake build`.\n    # Note, this input takes precedence over `auto-config`.\n    # Allowed values: \"true\" | \"false\" | \"default\".\n    build: \"\"\n\n    # Run `lake test`.\n    # Note, this input takes precedence over `auto-config`.\n    # Allowed values: \"true\" | \"false\" | \"default\".\n    test: \"\"\n    \n    # Run `lake lint`.\n    # Note, this input takes precedence over `auto-config`.\n    # Allowed values: \"true\" | \"false\" | \"default\".\n    lint: \"\"\n\n    # Build arguments to pass to `lake build {build-args}`.\n    # For example, `build-args: \"--quiet\"` will run `lake build --quiet`.\n    # By default, `lean-action` calls `lake build` with no arguments.\n    build-args: \"\"\n\n    # By default, `lean-action` attempts to automatically detect a Mathlib dependency and run `lake exe cache get` accordingly.\n    # Setting `use-mathlib-cache` will override automatic detection and run (or not run) `lake exe cache get`.\n    # Project must be downstream of Mathlib to use the Mathlib cache.\n    # Allowed values: \"true\" | \"false\" | \"auto\".\n    # Default: \"auto\"\n    use-mathlib-cache: \"\"\n\n    # Check if the repository is eligible for the Reservoir.\n    # Allowed values: \"true\" | \"false\".\n    # Default: \"false\"\n    check-reservoir-eligibility: \"\"\n    \n    # Check environment with lean4checker.\n    # Lean version must be 4.8 or higher.\n    # The version of lean4checker is automatically detected using `lean-toolchain`.\n    # Allowed values: \"true\" | \"false\".\n    # Default: \"false\"\n    lean4checker: \"\"\n    \n    # Enable GitHub caching.\n    # Allowed values: \"true\" or \"false\".\n    # If use-github-cache input is not provided, the action will use GitHub caching by default.\n    # Default: \"true\"\n    use-github-cache: \"\"\n\n    # The directory where `lean-action` will look for a Lake package and run `lake build`, etc.\n    # Allowed values: a valid directory containing a Lake package.\n    # If lake-package-directory is not provided, `lean-action` will use the root directory of the repository by default.\n    lake-package-directory: \"\"\n```\n\n## Output Parameters\n\n`lean-action` provides the following output parameters for downstream steps:\n\n- `build-status`\n  - Values: \"SUCCESS\" | \"FAILURE\" | \"\"\n- `test-status`\n  - Values: \"SUCCESS\" | \"FAILURE\" | \"\"\n- `lint-status`\n  - Values: \"SUCCESS\" | \"FAILURE\" | \"\"\n\nNote, a value of empty string indicates `lean-action` did not run the corresponding feature.\n\n### Example: Use `test-status` output parameter in downstream step\n\n```yaml\n- name: \"run `lean-action` with `lake test`\" \n  id: lean-action\n  uses: leanprover/lean-action@v1\n  continue-on-error: true\n  with:\n    test: true\n\n- name: log `lean-action` `test-status` output\n  env:\n    TEST_STATUS: ${{ steps.lean-action.outputs.test-status }}\n  run: echo \"Test status: $TEST_STATUS\"\n```\n\n## Additional Examples\n\n### Check package for reservoir eligibility\n\n```yaml\n- uses: leanprover/lean-action@v1\n  with:\n    check-reservoir-eligibility: true\n```\n\n### Don't run `lake test` or use Mathlib cache\n\n```yaml\n- uses: leanprover/lean-action@v1\n  with:\n    test: false\n    use-mathlib-cache: false\n```\n\n### Run lake build with `--wfail`\n\n```yaml\n- uses: leanprover/lean-action@v1\n  with:\n    build-args: \"--wfail\"\n```\n\n### Run additional steps after `lean-action` using the Lean environment\n\nAfter calling `lean-action` you can leverage the Lean environment in later workflow steps.\n\nFor example, `leanprover-community/import-graph` uses the setup from `lean-action` to test the `graph` executable with `lake exe graph`:\n\n```yaml\nsteps:\n  - uses: leanprover/lean-action@v1\n    with:\n      check-reservoir-eligibility: true\n  # use setup from lean-action to perform the following steps\n  - name: verify `lake exe graph` works\n    run: |\n      lake exe graph\n      rm import_graph.dot\n```\n\n## Projects which use `lean-action`\n\n- [leanprover-community/aesop](https://github.com/leanprover-community/aesop/blob/master/.github/workflows/build.yml#L16)\n- [leanprover-community/import-graph](https://github.com/leanprover-community/import-graph/blob/main/.github/workflows/build.yml#L8)\n\n## Keep the action updated with `dependabot`\n\nBecause Lean is under heavy development, changes to Lean or Lake could break outdated versions of `lean-action`. You can configure [dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates) to automatically create a PR to update `lean-action` when a new stable version is released.\n\nHere is an example `.github/dependabot.yml` which configures `dependabot` to check daily for updates to all GitHub actions in your repository:\n\n```yaml\nversion: 2\nupdates:\n  - package-ecosystem: \"github-actions\" \n    directory: \"/\"\n    schedule:\n      interval: \"daily\"\n```\n\nSee the [dependabot documentation](https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) for all configuration options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanprover%2Flean-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleanprover%2Flean-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleanprover%2Flean-action/lists"}