Cartoon gears and neon rolling marbles rolling through a track

Manage and monitor workflows in GitHub Actions

Bekah Whittle
Bekah Whittle // Director, Field Services // GitHub

Whether you're diving into individual workflows, seeking an administrative viewpoint with metadata outputs, or organizing workflow files, GitHub Actions provides the tools you need. In this guide, we'll walk you through the essentials of managing and monitoring workflows, using real-world insights to ensure you harness the platform's full potential. Coyote Logistics will join us along the way to add expert insight on managing workflow files. \

In this guide, you will learn:

  • How to rerun failed workflows directly from the Actions tab for quick troubleshooting

  • Techniques for diving into YAML files to understand and modify the specifics of each workflow

  • Ways to analyze job usage metrics for resource optimization and budgeting decisions

Analyzing workflows from the Actions tab

A repository’s Actions tab provides a clear snapshot of all its workflows. This centralized view is essential for quick checks on workflow statuses. As the number of workflows grows, some might be hidden to keep the interface neat. But remember, the Actions tab is just a starting point.

Rerunning workflows 

Occasionally, workflows might fail due to unpredictable reasons like flaky tests (software tests producing both successful and unsuccessful outcomes, even in the absence of any alterations to the code or testing parameters). Instead of diving deep into troubleshooting immediately, a quick solution is to rerun the workflow. Actions offers an easy rerun option, helping you address minor hiccups without delay. This can be done by selecting Re-run all jobs after selecting the workflow in the Actions tab. 

Viewing job usage

Effective workflow management goes beyond just checking if a job passed or failed. It involves understanding the resources it consumed. With Actions, you can easily view metrics like the time taken and cost associated with each job. This data aids in optimization and budgeting decisions. After selecting a workflow in the Actions tab, you will see a Usage tab on the right hand side where you can find this information. 

Analyzing workflow details in the <> code section

While the Actions tab provides a great overview, the heart of your workflows lie within the repository's code. To gain a comprehensive understanding of each workflow, diving into the code is essential.

Locating workflows

All your workflows reside in the .github folder of your repository. Inside, you'll find another folder named .github/workflows. Each workflow is represented here as a YAML file.

Reviewing workflows 

By navigating to these YAML files, you can view the specifics of each workflow: the triggers, Actions taken, and their sequence. This is especially useful for troubleshooting or when considering modifications.

Bundling with scripts 

Often, workflows might be associated with certain scripts to automate specific tasks. These scripts can be found bundled within the same .github directory. For instance, a script might handle deployment based on label changes.

We focus on functional clarity over strict naming conventions when it comes to structuring and managing workflow files. Workflow files are easily discoverable, as they primarily reside in the designated 'workflows' directory, but more importantly, they should be easily identifiable. We’ve  experimented with housing workflows in a private GitHub Actions repository, which allows for more flexible versioning, but this can also lead to redundancy.

Chris Taylor
Chris Taylor // Enterprise Architect // Coyote Logistics

Markdown details in workflow files

Actions not only allow you to monitor job statuses but also offer a deeper layer of insight through markdown outputs within workflow files. These markdown details present a wealth of information, from job outcomes to intricate metadata.

Using Marketplace Actions

When you incorporate Actions from GitHub Marketplace, many of them come with built-in markdown outputs. These outputs can provide valuable context, performance metrics, or even diagnostic information. Therefore, it's worth exploring the markdown sections for Actions you adopt from Marketplace.

Scripting your own markdown

For those looking for a tailored approach, Actions also enables you to script your own markdown outputs. By customizing these sections, you can include specific metrics or logs that are crucial for your project. This granularity is invaluable, providing a comprehensive view of workflow events and ensuring optimal efficiency and clarity.

Adding markdown output to workflows is simple:

  - name: Adding markdown
    run: echo '### Hello world! 🚀' >> $GITHUB_STEP_SUMMARY

Screenshot of the GitHub job summary showing the markdown-added "Hello world!"

Screenshot of the GitHub job summary showing the markdown-added "Hello world!"

For more information, check out our full documentation for adding workflow commands.

Up next: Advanced automation testing strategies with GitHub Actions

Looking to take your testing to the next level? Don't miss our next guide on advanced testing with GitHub Actions. Learn how to scale your testing efforts effectively and make the most out of GitHub Marketplace.