Skip to main content

Monitoring and Analytics

1. Viewing Workflow Runs

Field Description Example
workflow_run.id Unique identifier for the workflow run 123456789
workflow_run.name Name of the workflow run Build and Test
workflow_run.status Status of the workflow run (success, failure, cancelled) success
workflow_run.conclusion Conclusion of the workflow run (success, failure, cancelled) success
workflow_run.created_at Time when the workflow run was created 2023-10-01T12:00:00Z
workflow_run.updated_at Time when the workflow run was last updated 2023-10-01T12:05:00Z

Example: Fetching workflow run details via API

curl -H "Authorization: Bearer <token>" \
  https://api.github.com/repos/<owner>/<repo>/actions/runs/<run_id>
Note: You can view workflow runs in the GitHub UI under the Actions tab of your repository.

2. Checking Job Status

Field Description Values
job.status Current status of the job success, failure, cancelled
job.conclusion Final conclusion of the job after all steps success, failure, cancelled, skipped
job.name Name of the job as defined in workflow build, test

Example: Using job status in a workflow

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check job status
        run: |
          echo "Job status is ${{ job.status }}"
          echo "Job conclusion is ${{ job.conclusion }}"
Note: The job.status can change during the job execution, while job.conclusion is final.

3. Viewing Job Logs

Log Type Description Access Method
Job Logs Logs generated during job execution Available in the Actions tab of your repository
Workflow Logs Logs from the entire workflow run Accessible via the workflow run page
Step Logs Logs from individual steps in a job Viewable within the job logs under each step

Example: Accessing Job Logs

gh run view <run-id> --logs
Note: Logs are retained for 90 days by default.
Warning: Sensitive information in logs should be redacted before sharing.

4. Downloading Workflow Logs

Option Values Description
workflow_run.id 123456789 Unique identifier for the workflow run
log_file workflow.log Name of the log file to download

Example: Downloading Logs via CLI

gh run download 123456789 --name workflow.log
Note: Logs are available for 90 days after a workflow completes.
Warning: Ensure you have appropriate permissions to download logs from the repository.

5. Using Workflow Insights

Example: Accessing Workflow Insights

name: Workflow Insights Example
on:
  push:
    branches: [ main ]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Run analysis
        run: echo "Analyzing workflow performance"
Insight Type Description Access Method Notes
Workflow Duration Time taken to complete a workflow run GitHub UI / API Shows average and peak durations
Job Failures Count and details of failed jobs GitHub UI / API Includes failure reasons and logs
Resource Usage Compute and storage usage per workflow GitHub UI / API Helps identify resource-intensive workflows
Note: Workflow Insights are available for GitHub Actions workflows in repositories with GitHub Pro or Enterprise plans.

Key Features of Workflow Insights

  • Real-time monitoring of workflow performance
  • Detailed breakdown of job execution times
  • Failure analysis with root cause hints
  • Resource consumption tracking

6. Monitoring Runner Usage

Property Description Values
runner.name Name of the runner ubuntu-latest, macos-latest, windows-latest
runner.os Operating system of the runner Linux, macOS, Windows
runner.arch Architecture of the runner x64, arm64
runner.labels Labels assigned to the runner self-hosted, ubuntu, docker

Example: Using runner labels in workflow

jobs:
  build:
    runs-on: [self-hosted, ubuntu]
    steps:
      - name: Print runner info
        run: echo "Runner OS is ${{ runner.os }} and arch is ${{ runner.arch }}"
Note: Runner usage data is available via GitHub Actions metrics dashboard and can be used to optimize resource allocation.

7. Tracking Workflow Duration

Property Description Values
github.event.workflow_run.duration Duration of the workflow run in seconds 120
github.event.workflow_run.created_at Timestamp when the workflow run was created 2025-04-01T10:00:00Z
github.event.workflow_run.updated_at Timestamp when the workflow run was last updated 2025-04-01T10:02:00Z

Example: Calculate Workflow Duration

const startTime = new Date(process.env.WORKFLOW_START_TIME);
const endTime = new Date();
const durationInSeconds = (endTime - startTime) / 1000;

console.log("Workflow duration: " + durationInSeconds + " seconds");
Note: The duration is calculated from the start to end of the workflow run, including all jobs and steps.

8. Viewing Workflow Dependencies

Dependency Type Description Visibility Usage
GitHub Actions Workflow dependencies within the same repository NEW Triggered by events like push, pull_request
External Workflows Workflows in other repositories or organizations Public or private based on repo settings Can be called using workflow_call
Reusable Workflows Predefined workflow files that can be reused across repositories Published to GitHub or private repositories Referenced using uses in workflow files

Example: Reusable Workflow Call

name: Reusable Workflow Example
on:
  push:
    branches:
      - main

jobs:
  build:
    uses: octocat/repo/.github/workflows/build.yml@v1
    with:
      environment: production
Note: Reusable workflows must be defined with on.workflow_call to accept inputs and trigger events.

Key Points

  • Dependencies can be internal (same repo) or external (different repo)
  • Reusable workflows provide modularity and reusability
  • Workflow dependencies are managed through uses and workflow_call
  • Dependencies can be versioned using tags or branches

9. Using Workflow API

Endpoint Method Description Notes
/repos/{owner}/{repo}/actions/workflows GET Lists workflows in a repository Includes workflow IDs and names
/repos/{owner}/{repo}/actions/workflows/{workflow_id} GET Gets a specific workflow Returns detailed workflow metadata
/repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs GET Lists workflow runs Supports filtering by branch, status, etc.
/repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs/{run_id} GET Gets a specific workflow run Includes logs, status, and timing info
/repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs/{run_id}/jobs GET Lists jobs in a workflow run Shows job status and logs

Example: Fetching Workflow Runs

curl -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/Hello-World/actions/workflows/12345/runs

Example: Getting Workflow Run Details

const run = {
  id: 67890,
  status: "completed",
  conclusion: "success",
  created_at: "2025-04-01T10:00:00Z",
  updated_at: "2025-04-01T10:05:00Z"
};
Note: Workflow runs can be filtered using query parameters like ?branch=main&status=success.

10. Setting Up Alerts

Example: Basic Alert Configuration

on:
  workflow_run:
    workflows: [&#34;Build&#34;]
    status: [&#34;failure&#34;]

jobs:
  alert:
    runs-on: ubuntu-latest
    steps:
      - name: Send Alert
        uses: actions/github-script@v6
        with:
          script: |
            const { data: issue } = await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: &#34;Workflow Failed: Build&#34;,
              body: &#34;The build workflow has failed. Please check the logs.&#34;
            })
Property Description Values
on.workflow_run.status Status to trigger alert success, failure, canceled
on.workflow_run.workflows Workflow names to monitor Array of workflow names
github.rest.issues.create GitHub API endpoint to create issue Object with owner, repo, title, body
Note: Alerts can be sent via email, Slack, or other notification services using webhooks.
Warning: Ensure proper permissions are set for the GitHub App or token used to create issues.

11. Analyzing Billing Usage

Field Description Notes
workflow_runs Total number of workflow runs Includes all runs, successful and failed
job_runs Total number of job runs Each workflow can have multiple jobs
minutes_used Minutes consumed by workflows Billing is based on compute minutes
storage_gb Storage used in gigabytes Includes artifacts and caches
actions_minutes Minutes used for actions Used to calculate billing costs

Example: Billing Usage Query

const billingData = {
  "workflow_runs": 120,
  "job_runs": 360,
  "minutes_used": 4500,
  "storage_gb": 2.5,
  "actions_minutes": 4500
};

console.log("Total minutes used: " + billingData.actions_minutes);
Note: Billing data is updated daily and can be accessed via the GitHub API or through the Actions billing page in your repository settings.

12. Creating Custom Dashboards

Example: Setting up a custom dashboard with GitHub Actions metrics

name: Custom Dashboard Setup
on:
  schedule:
    - cron: '0 */15 * * *'
  workflow_dispatch:

jobs:
  dashboard-setup:
    runs-on: ubuntu-latest
    steps:
      - name: Setup GitHub CLI
        uses: actions/setup-cli@v1
        with:
          cli: gh

      - name: Fetch workflow runs
        run: |
          gh api repos/${{ github.repository }}/actions/runs \
            --jq '.workflow_runs[] | {id: .id, name: .name, status: .status, conclusion: .conclusion}' \
            > workflow_runs.json

      - name: Process metrics
        run: |
          echo "Processing dashboard data..."
          # Custom logic to aggregate and format metrics
Component Description Usage
Dashboard A visual representation of key metrics and data from GitHub Actions workflows Used to monitor performance, identify bottlenecks, and track success rates
Metrics Quantitative measures such as run duration, success rate, and failure count Tracked over time to identify trends and anomalies
Data Source GitHub Actions API or third-party tools like Prometheus and Grafana Provides real-time and historical data for dashboard visualization
Note: Custom dashboards can be built using tools like Grafana or Prometheus to visualize GitHub Actions metrics.

Comparison: GitHub Actions vs External Dashboard Tools

  • GitHub Actions: Built-in metrics, no external setup required
  • Grafana: Advanced visualization and alerting capabilities
  • Prometheus: Powerful querying and integration with other systems

Was this article helpful?