gh actions-importer forecast command to estimate potential GitHub Actions usage from historical CI pipeline runs (example uses Jenkins). The forecast analyzes historical builds and computes metrics — such as total execution minutes, queue times, and concurrency — useful for planning runner capacity or estimating GitHub-hosted runner costs.
The Jenkins server must have the Paginated Builds plugin installed so the importer can retrieve large volumes of build history without timing out.
Example command:
Install the Jenkins “Paginated Builds” plugin on the target Jenkins server before running
gh actions-importer forecast jenkins. For Jenkins instances with a lot of historical builds, paginated access prevents request timeouts and ensures the importer can retrieve the full run history.What the forecast command does
- Extracts historical build records from your CI provider (Jenkins in this example).
- Computes execution-time statistics, queue-time summaries, and concurrent-job distributions.
- Produces:
- A jobs JSON file containing one object per build (raw extracted records).
- A human-readable
forecast_report.mdsummarizing the computed metrics for capacity planning.
- Jenkins Paginated Builds plugin: https://plugins.jenkins.io/paginated-builds
- Actions Importer Jenkins docs: https://github.com/actions-importer/preview/tree/main/jenkins#paginated-builds-plugin
Initial run (example failure when plugin is missing)
If the Paginated Builds plugin is not installed, the forecast command will fail and log a message instructing you to install the plugin. Example failing run and trimmed logs:Install the Paginated Builds plugin in Jenkins
- Open Jenkins → Manage Jenkins → Manage Plugins.
- Search for “Paginated Builds” in the Available plugins tab.
- Install the plugin and restart Jenkins when prompted.
Rerun the forecast — handle HTTP caching issues
Even after installing the plugin, you may still see the same error if the importer is using previously cached HTTP responses that predate the plugin installation. To force fresh requests, re-run the forecast with the--no-http-cache flag.
You can check the forecast command options:
If you still see the plugin-related error after installing Paginated Builds, add
--no-http-cache to the forecast command to ensure the importer queries Jenkins live instead of using cached plugin lists.--no-http-cache:
Output artifacts
The forecast run produces two primary outputs:| Artifact | Purpose | Example path |
|---|---|---|
| Jobs JSON | Raw list of extracted builds; one object per build with timestamps and result details | tmp/forecast/jobs/05-22-2025-09-40_jobs_0.json |
| Forecast report (Markdown) | Human-readable summary of totals, execution-time stats, queue times, and concurrency | tmp/forecast/forecast_report.md |
Example: jobs JSON snippet
The jobs JSON file contains one object per build record. Each object includes fields such asid, result, queue_time, start_time, finish_time, and definition_id.
Example: forecast_report.md (trimmed)
The generatedforecast_report.md summarizes totals and statistical metrics that aid capacity planning — such as total execution minutes, median and percentile values, and concurrency distributions.
- GitHub-hosted runner minute consumption.
- The number of concurrent self-hosted runners required to achieve desired throughput.
- Cost planning and migration strategy when moving pipelines to GitHub Actions.
Recap and troubleshooting checklist
- Purpose:
gh actions-importer forecast jenkinscomputes GitHub Actions usage estimates from historical Jenkins builds. - Precondition: Install the Jenkins Paginated Builds plugin and restart Jenkins.
- If you see the plugin error after installation:
- Re-run the command with
--no-http-cacheto bypass stale HTTP responses.
- Re-run the command with
- Outputs:
- Jobs JSON file (raw build records).
forecast_report.md(human-readable usage summary).