From 393cbcee6e476466cd6186211879604e5475080e Mon Sep 17 00:00:00 2001 From: Siddhartha Basu Date: Sat, 16 May 2026 12:52:33 +0000 Subject: [PATCH] docs(readme): revamp with structured command reference and badges MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite README with table of contents, full CLI help output, detailed command reference sections for all 15 commands, Go version and GitHub release badges, and correction of CI badge URL to use filename instead of workflow name. Remove docs/README.md and misc stats badges. 💘 Generated with Crush Assisted-by: Crush:deepseek/deepseek-v4-pro --- README.md | 305 ++++++++++++++++++++++++++++++++++++++++---- docs/README.md | 340 ------------------------------------------------- 2 files changed, 283 insertions(+), 362 deletions(-) delete mode 100644 docs/README.md diff --git a/README.md b/README.md index ace4677..27392c6 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,285 @@ # github-actions -[![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](LICENSE) + +[![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](LICENSE) +![Continuous integration](https://github.com/dictybase-docker/github-actions/actions/workflows/ci.yaml/badge.svg?branch=develop) [![Code coverage](https://codecov.io/gh/dictybase-docker/github-actions/branch/develop/graph/badge.svg)](https://codecov.io/gh/dictybase-docker/github-actions) -[![Maintainability](https://api.codeclimate.com/v1/badges/27d8dea5aa1373847404/maintainability)](https://codeclimate.com/github/dictybase-docker/github-actions/maintainability) -![Last commit](https://badgen.net/github/last-commit/dictyBase-docker/github-actions/develop) -[![Funding](https://badgen.net/badge/NIGMS/Rex%20L%20Chisholm,DCR/yellow?list=|)](https://reporter.nih.gov/project-details/10024726) - -cli to manage dictyBase github actions - -# [Cli documentation](docs/README.md) - -# Misc. Badges -![Issues](https://badgen.net/github/issues/dictyBase-docker/github-actions) -![Open Issues](https://badgen.net/github/open-issues/dictyBase-docker/github-actions) -![Closed Issues](https://badgen.net/github/closed-issues/dictyBase-docker/github-actions) -![Total PRS](https://badgen.net/github/prs/dictyBase-docker/github-actions) -![Open PRS](https://badgen.net/github/open-prs/dictyBase-docker/github-actions) -![Closed PRS](https://badgen.net/github/closed-prs/dictyBase-docker/github-actions) -![Merged PRS](https://badgen.net/github/merged-prs/dictyBase-docker/github-actions) -![Commits](https://badgen.net/github/commits/dictyBase-docker/github-actions/develop) -![Branches](https://badgen.net/github/branches/dictyBase-docker/github-actions) -![Tags](https://badgen.net/github/tags/dictyBase-docker/github-actions/?color=cyan) -![GitHub repo size](https://img.shields.io/github/repo-size/dictyBase-docker/github-actions?style=plastic) -![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/dictyBase-docker/github-actions?style=plastic) +![Last commit](https://badgen.net/github/last-commit/dictybase-docker/github-actions/develop) +[![Funding](https://badgen.net/badge/Funding/Rex%20L%20Chisholm,dictyBase,DCR/yellow?list=|)](https://reporter.nih.gov/project-details/10024726) + +![Go](https://badgen.net/static/go/1.25/00ADD8) +[![GitHub release](https://badgen.net/github/release/dictybase-docker/github-actions)](https://github.com/dictybase-docker/github-actions/releases) + +CLI to manage dictyBase GitHub actions, deployments, and repository operations. + +## Contents + +- [Available commands](#available-commands) +- [Commands](#commands) + - [issue-comment-report](#issue-comment-report) + - [issue-comment-count](#issue-comment-count) + - [store-report](#store-report) + - [deploy-status](#deploy-status) + - [share-deploy-payload](#share-deploy-payload) + - [get-cluster-credentials](#get-cluster-credentials) + - [deploy-chart](#deploy-chart) + - [files-committed](#files-committed) + - [batch-multi-repo](#batch-multi-repo) + - [parse-chatops-deploy](#parse-chatops-deploy) + - [report-as-comment](#report-as-comment) + - [migrate-repos](#migrate-repos) + - [analytics-report](#analytics-report) + - [setup-dagger-checksum](#setup-dagger-checksum) + - [setup-dagger-bin](#setup-dagger-bin) +- [Full CLI documentation](#full-cli-documentation) + +## Available commands + +``` +NAME: + gh-action - run github action + +USAGE: + github-actions [global options] command [command options] [arguments...] + +VERSION: + 1.0.0 + +COMMANDS: + issue-comment-report, icr reports no of comments for every issue + issue-comment-count, icc reports total no of issues and comments since a particular date + store-report, ur save report to s3 storage + deploy-status, ds create a github deployment status + share-deploy-payload, sdp share deployment payload data in github workflow + get-cluster-credentials, gcre get kubernetes cluster credentials using gcloud + doc generate markdown documentation + deploy-chart, dc deploy helm chart + files-committed, fc outputs list of file committed in a git push or pull-request + batch-multi-repo, bmr Commit a file to multiple repositories + parse-chatops-deploy, pcd parses chatops deploy command and extracts ref and image tag values + report-as-comment, rac generate ontology report in pull request comment + migrate-repos, mr fork and migrate repositories to a different owner or organization + analytics-report, ar generate google analytics report of sessions,users,pageviews in csv format. + setup-dagger-checksum, sc setup checksum of dagger binary + setup-dagger-bin, sd setup dagger command line + help, h Shows a list of commands or help for one command + +GLOBAL OPTIONS: + --log-format value format of the log, either of json or text. (default: "json") + --log-level value log level for the application (default: "error") + --token value, -t value github personal access token [$GITHUB_TOKEN] + --repository value, -r value Github repository + --owner value Github repository owner (default: "dictyBase") + --help, -h show help + --version, -v print the version +``` + +## Commands + +### issue-comment-report + +Reports number of comments for every issue in a repository. Outputs a CSV file. + +``` +gh-action issue-comment-report [--token TOKEN] [--repository REPO] [--owner OWNER] [--output FILE] [--state STATE] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--output` | *(auto-generated)* | CSV output file path | +| `--state` | `all` | Issue state filter (`open`, `closed`, `all`) | + +### issue-comment-count + +Reports total number of issues and comments since a particular date. Outputs a CSV file. + +``` +gh-action issue-comment-count --date DATE [--output FILE] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--date, -d` | *(required)* | Start date for counting (e.g. `2024-01-01`) | +| `--output, -o` | `stdout` | Output file path | + +### store-report + +Upload a report file to S3-compatible storage. + +``` +gh-action store-report --input FILE --upload-path PATH [--access-key KEY] [--secret-key KEY] [--s3-server HOST] [--s3-server-port PORT] [--s3-bucket BUCKET] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--input` | *(required)* | Input file to upload | +| `--upload-path, -p` | *(required)* | Full upload path inside the bucket | +| `--access-key, --akey` | *(auto)* | S3 access key | +| `--secret-key, --skey` | *(auto)* | S3 secret key | +| `--s3-server` | `minio` | S3 server endpoint | +| `--s3-server-port` | *(auto)* | S3 server port | +| `--s3-bucket` | `report` | S3 bucket name | + +### deploy-status + +Create a GitHub deployment status for a given deployment. + +``` +gh-action deploy-status --deployment_id ID --state STATE [--url URL] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--deployment_id` | *(required)* | Deployment identifier | +| `--state` | *(required)* | Deployment state | +| `--url` | `""` | URL associated with this status | + +### share-deploy-payload + +Share deployment payload data in a GitHub workflow by writing key-value pairs to `$GITHUB_OUTPUT`. + +``` +gh-action share-deploy-payload --payload-file FILE +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--payload-file, -f` | *(required)* | Path to the JSON deploy payload file | + +### get-cluster-credentials + +Get Kubernetes cluster credentials using gcloud. + +``` +gh-action get-cluster-credentials --cluster NAME --project ID --zone ZONE +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--cluster` | *(required)* | Kubernetes cluster name | +| `--project` | *(required)* | Google Cloud project ID | +| `--zone` | *(required)* | Compute zone for the cluster | + +### deploy-chart + +Deploy a Helm chart to a Kubernetes cluster. + +``` +gh-action deploy-chart --name NAME --path PATH --namespace NS --image-tag TAG +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--name` | *(required)* | Chart name | +| `--path` | *(required)* | Relative chart path from repo root | +| `--namespace` | *(required)* | Kubernetes namespace | +| `--image-tag` | *(required)* | Docker image tag | + +### files-committed + +Output list of files committed in a git push or pull request event. + +``` +gh-action files-committed --payload-file FILE [--event-type TYPE] [--output FILE] [--include-file-suffix SUFFIX] [--skip-deleted] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--payload-file, -f` | *(required)* | Path to the event payload JSON | +| `--event-type, -e` | `push` | Event type (`push` or `pull-request`) | +| `--output, -o` | `stdout` | Output file path | +| `--include-file-suffix, --ifs` | `""` | Only report files with this suffix | +| `--skip-deleted, --sd` | `false` | Skip deleted files | + +### batch-multi-repo + +Commit a file to multiple repositories in a single operation. + +``` +gh-action batch-multi-repo --input-file FILE --repository-list FILE --repository-path PATH [--branch BRANCH] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--input-file, -i` | *(required)* | File to commit | +| `--repository-list, -l` | *(required)* | File with list of repository names (one per line) | +| `--repository-path, --rp` | *(required)* | Relative path in target repositories | +| `--branch, -b` | `develop` | Target branch (must already exist) | + +### parse-chatops-deploy + +Parse a ChatOps deploy command and extract ref and image tag values. + +``` +gh-action parse-chatops-deploy --payload-file FILE [--frontend] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--payload-file, -f` | *(required)* | Path to JSON payload | +| `--frontend` | `false` | Set when deploying a frontend web app | + +### report-as-comment + +Generate an ontology report and post it as a pull request comment. + +``` +gh-action report-as-comment --commit-list-file FILE --pull-request-id ID --report-dir DIR [--ref REF] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--commit-list-file, -c` | *(required)* | File with list of committed files | +| `--pull-request-id, --id` | *(required)* | Pull request ID to comment on | +| `--report-dir, -d` | *(required)* | Directory containing ontology reports | +| `--ref` | `""` | Git reference (tag or commit ID) | + +### migrate-repos + +Fork and migrate repositories to a different owner or organization. + +``` +gh-action migrate-repos --owner-to-migrate OWNER --repo-to-move REPO [--repo-to-move REPO...] [--poll-for SECONDS] [--poll-interval SECONDS] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--owner-to-migrate, --om` | *(required)* | Target owner/organization name | +| `--repo-to-move, -m` | *(required, repeatable)* | Repository names to migrate | +| `--poll-for` | `60` | Max polling duration in seconds | +| `--poll-interval` | `2` | Polling interval in seconds | + +### analytics-report + +Generate a Google Analytics report (sessions, users, pageviews) in CSV format. + +``` +gh-action analytics-report --view-id ID --credential-file FILE --start-date DATE [--end-date DATE] [--output FILE] +``` + +| Flag | Default | Description | +|------|---------|-------------| +| `--view-id` | *(required)* | Google Analytics view ID | +| `--credential-file, -c` | *(required)* | Google service account credential file | +| `--start-date, -s` | *(required)* | Start date (`YYYY-MM-DD` format) | +| `--end-date, -e` | `today` | End date (`YYYY-MM-DD` format) | +| `--output, -o` | `stdout` | Output CSV file name | + +### setup-dagger-checksum + +Verify the Dagger binary checksum from stdin. + +``` +gh-action setup-dagger-checksum < checksum_file +``` + +### setup-dagger-bin + +Set up the Dagger CLI binary and add it to `$PATH`. + +``` +gh-action setup-dagger-bin +``` + +## Full CLI documentation + +Run `gh-action doc` to generate the complete CLI reference in markdown format with all flags and options. diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 1ad1c15..0000000 --- a/docs/README.md +++ /dev/null @@ -1,340 +0,0 @@ -% gh-action(8) - -% - -# NAME - -gh-action - run github action - -# SYNOPSIS - -gh-action - -``` -[--help|-h] -[--log-format]=[value] -[--log-level]=[value] -[--owner]=[value] -[--repository|-r]=[value] -[--token|-t]=[value] -[--version|-v] -``` - -**Usage**: - -``` -gh-action [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] -``` - -# GLOBAL OPTIONS - -**--help, -h**: show help - -**--log-format**="": format of the log, either of json or text. (default: json) - -**--log-level**="": log level for the application (default: error) - -**--owner**="": Github repository owner (default: dictyBase) - -**--repository, -r**="": Github repository - -**--token, -t**="": github personal access token - -**--version, -v**: print the version - - -# COMMANDS - -## issue-comment-report, icr - -reports no of comments for every issue - -**--output**="": file where csv format output is written, creates a timestamp based file by default - -**--state**="": state of the issue for filtering (default: all) - -## store-report, ur - -save report to s3 storage - -**--access-key, --akey**="": access key for S3 server, required based on command run - -**--input**="": input file that will be uploaded - -**--s3-bucket**="": S3 bucket where the data will be uploaded (default: report) - -**--s3-server**="": S3 server endpoint (default: minio) - -**--s3-server-port**="": S3 server port - -**--secret-key, --skey**="": secret key for S3 server, required based on command run - -**--upload-path, -p**="": full upload path inside the bucket - -## deploy-status, ds - -create a github deployment status - -**--deployment_id**="": Deployment identifier (default: 0) - -**--state**="": The state of the deployment status - -**--url**="": The url that is associated with this status - -## share-deploy-payload, sdp - -share deployment payload data in github workflow - -**--payload-file, -f**="": Full path to the file that contain the deploy payload - -## get-cluster-credentials, gcre - -get kubernetes cluster credentials using gcloud - -**--cluster**="": Name of k8s cluster - -**--project**="": Google cloud project id - -**--zone**="": Compute zone for the cluster - -## doc - -generate markdown documentation - -## deploy-chart, dc - -deploy helm chart - -**--image-tag**="": Docker image tag - -**--name**="": Name of the chart - -**--namespace**="": Kubernetes namespace - -**--path**="": Relative chart path from the root of the repo - -## files-committed, fc - -outputs list of file committed in a git push or pull-request - -**--event-type, -e**="": Name of the event, either or push or pull-request (default: push) - -**--include-file-suffix, --ifs**="": file with the given suffix will only be reported - -**--output, -o**="": Name of output file, defaults to stdout - -**--payload-file, -f**="": Full path to the file that contain the event payload - -**--skip-deleted, --sd**: skip deleted files in the commit(s) - -## batch-multi-repo, bmr - -Commit a file to multiple repositories - -**--branch, -b**="": repository branch(should exist before committing) (default: develop) - -**--input-file, -i**="": file that will be committed to repository - -**--repository-list, -l**="": file with list of repositories name, one repository in every line - -**--repository-path, --rp**="": relative path(from root) in the repository for the input file - -## parse-chatops-deploy, pcd - -parses chatops deploy command and extracts ref and image tag values - -**--frontend**: used if deploying frontend web app (needed for updating image-tag correctly) - -**--payload-file, -f**="": path to JSON payload - -## report-as-comment, rac - -generate ontology report in pull request comment - -**--commit-list-file, -c**="": file that contain a list of committed file in the push event - -**--pull-request-id, --id**="": id of a pull-request where the comment should be made (default: 0) - -**--report-dir, -d**="": folder containing ontology reports - -## help, h - -Shows a list of commands or help for one command - -% gh-action(8) - -% - -# NAME - -gh-action - run github action - -# SYNOPSIS - -gh-action - -``` -[--help|-h] -[--log-format]=[value] -[--log-level]=[value] -[--owner]=[value] -[--repository|-r]=[value] -[--token|-t]=[value] -[--version|-v] -``` - -**Usage**: - -``` -gh-action [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...] -``` - -# GLOBAL OPTIONS - -**--help, -h**: show help - -**--log-format**="": format of the log, either of json or text. (default: json) - -**--log-level**="": log level for the application (default: error) - -**--owner**="": Github repository owner (default: dictyBase) - -**--repository, -r**="": Github repository - -**--token, -t**="": github personal access token - -**--version, -v**: print the version - - -# COMMANDS - -## issue-comment-report, icr - -reports no of comments for every issue - -**--output**="": file where csv format output is written, creates a timestamp based file by default - -**--state**="": state of the issue for filtering (default: all) - -## store-report, ur - -save report to s3 storage - -**--access-key, --akey**="": access key for S3 server, required based on command run - -**--input**="": input file that will be uploaded - -**--s3-bucket**="": S3 bucket where the data will be uploaded (default: report) - -**--s3-server**="": S3 server endpoint (default: minio) - -**--s3-server-port**="": S3 server port - -**--secret-key, --skey**="": secret key for S3 server, required based on command run - -**--upload-path, -p**="": full upload path inside the bucket - -## deploy-status, ds - -create a github deployment status - -**--deployment_id**="": Deployment identifier (default: 0) - -**--state**="": The state of the deployment status - -**--url**="": The url that is associated with this status - -## share-deploy-payload, sdp - -share deployment payload data in github workflow - -**--payload-file, -f**="": Full path to the file that contain the deploy payload - -## get-cluster-credentials, gcre - -get kubernetes cluster credentials using gcloud - -**--cluster**="": Name of k8s cluster - -**--project**="": Google cloud project id - -**--zone**="": Compute zone for the cluster - -## doc - -generate markdown documentation - -## deploy-chart, dc - -deploy helm chart - -**--image-tag**="": Docker image tag - -**--name**="": Name of the chart - -**--namespace**="": Kubernetes namespace - -**--path**="": Relative chart path from the root of the repo - -## files-committed, fc - -outputs list of file committed in a git push or pull-request - -**--event-type, -e**="": Name of the event, either or push or pull-request (default: push) - -**--include-file-suffix, --ifs**="": file with the given suffix will only be reported - -**--output, -o**="": Name of output file, defaults to stdout - -**--payload-file, -f**="": Full path to the file that contain the event payload - -**--skip-deleted, --sd**: skip deleted files in the commit(s) - -## batch-multi-repo, bmr - -Commit a file to multiple repositories - -**--branch, -b**="": repository branch(should exist before committing) (default: develop) - -**--input-file, -i**="": file that will be committed to repository - -**--repository-list, -l**="": file with list of repositories name, one repository in every line - -**--repository-path, --rp**="": relative path(from root) in the repository for the input file - -## parse-chatops-deploy, pcd - -parses chatops deploy command and extracts ref and image tag values - -**--frontend**: used if deploying frontend web app (needed for updating image-tag correctly) - -**--payload-file, -f**="": path to JSON payload - -## report-as-comment, rac - -generate ontology report in pull request comment - -**--commit-list-file, -c**="": file that contain a list of committed file in the push event - -**--pull-request-id, --id**="": id of a pull-request where the comment should be made (default: 0) - -**--ref**="": git reference name, tag or commit id - -**--report-dir, -d**="": folder containing ontology reports - -## migrate-repos, mr - -fork and migrate repositories to a different owner or organization - -**--owner-to-migrate, --om**="": owner name where the repositories will be migrated - -**--poll-for**="": threshold for polling forked repository(in seconds) (default: 60) - -**--poll-interval**="": polling interval for forked repository(in seconds) (default: 2) - -**--repo-to-move, -m**="": repositories that will be migrated, repeat the option for multiple values - -## help, h - -Shows a list of commands or help for one command -