Skip to content

Latest commit

 

History

History
189 lines (146 loc) · 6.52 KB

README.md

File metadata and controls

189 lines (146 loc) · 6.52 KB
Raw

✅ GitHub Check Runs Action

Documentation Maintenance License: MIT Twitter: dflydev Twitter: beausimensen

Create and manage one or more GitHub check runs per job.

GitHub Actions already creates a check run for every job. This is great if you can break your workflow into smaller jobs. But if any one job is doing several things for which you'd like feedback as it progresses you are out of luck.

This action allows you to create and manage GitHub check runs throughout the course of a single job.

🚀 Quick start

Just one, please

The following is a quick example showing how dflydev/check-runs-action can be used to report a check run.

jobs:
  build:
    name: Build PHP Library
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Set up PHP, with Composer and extensions
        uses: shivammathur/setup-php@v2
        with:
          php-version: 7.4
          coverage: pcov

      - name: PHPUnit
        id: phpunit
        continue-on-error: true
        run: ./vendor/bin/phpunit --coverage-text

      - name: Report PHPUnit Conclusion
        if: always()
        uses: dflydev/check-runs-action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          id: phpunit
          conclusion: ${{ steps.phpunit.outcome }}

Expect a bunch of things to happen

The following is a quick example showing how dflydev/check-runs-action can be used to create multiple check runs in advance with the status queued.

jobs:
  build:
    name: Build Laravel Application
    runs-on: ubuntu-latest
    steps:
      - name: Prepare Check Runs
        uses: dflydev/check-runs-action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          checks: |
            [
              { "id": "phpunit", "name": "PHPUnit" },
              { "id": "psalm", "name": "Psalm" },
              { "id": "phpcs", "name": "PHP_CodeSniffer" },
              { "id": "eslint", "name": "ESLint" },
              { "id": "assets", "name": "npm run production" },
              { "id": "dusk", "name": "Dusk" }
            ]
          status: "queued"

Before running an individual step (like phpunit, psalm, phpcs, eslint, assets or dusk), the status can be updated to in_progress.

jobs:
  build:
    steps:
      - name: Report PHPUnit Starting
        uses: dflydev/check-runs-action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          id: phpunit
          status: in_progress

Execute something that may pass or fail.

In order to actually do something meaningful with fails, you need to pass true for continue-on-error. It is also important to give these steps an id so that following actions (like check-runs-action) can capture the outcome.

jobs:
  build:
    steps:
      - name: PHPUnit
        id: phpunit
        continue-on-error: true
        run: ./vendor/bin/phpunit --coverage-text

After individual steps have been completed, they can be marked with their conclusion.

To work with continue-on-error, it is recommended to use steps.<step id>.outcome.

Set fail-on-error to true if the job should fail after reporting a failed conclusion.

jobs:
  build:
    steps:
      - name: Report PHPUnit Conclusion
        if: always()
        uses: dflydev/check-runs-action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          id: phpunit
          conclusion: ${{ steps.phpunit.outcome }}
          fail-on-error: true

Finally, steps that have not been marked with a conclusion can be finalized to a specifed conclusion. This ensures there will be no checks defined upfront stuck in a non-final state when the job ends.

jobs:
  build:
    steps:
      - name: Clean up checks
        if: always()
        uses: dflydev/check-runs-action@v1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          conclusion: cancelled

Author

👥 dflydev

👤 Beau Simensen

💡 Inspiration

This project was heavily inspired by GitHub Checks action. If you only need one check run per job and do not want to specify an arbitrary id, check out that action instead!

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

❤️ Support the development

Give a ⭐️ if this project helped you!

Did this project save you time? Did this project increase your productivity? Did this project solve a problem for you? Did this project make your life easier? Please also consider donating or buying a license!

📝 License

Copyright © 2020 dflydev.
This project is MIT licensed.