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 |
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 |
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
usesandworkflow_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: ["Build"]
status: ["failure"]
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: "Workflow Failed: Build",
body: "The build workflow has failed. Please check the logs."
})
| 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.