Improve table docs (#393)

Co-authored-by: Madhushree Ray <[email protected]>

.github/workflows/steampipe-anywhere.yml

@@ -0,0 +1,12 @@
+name: Release Steampipe Anywhere Components
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+
+jobs:
+  anywhere_publish_workflow:
+    uses: turbot/steampipe-workflows/.github/workflows/steampipe-anywhere.yml@main
+    secrets: inherit

README.md

@@ -45,6 +45,18 @@ from
   github_my_repository;
 ```
 
+## Engines
+
+This plugin is available for the following engines:
+
+| Engine        | Description
+|---------------|------------------------------------------
+| [Steampipe](https://steampipe.io/docs) | The Steampipe CLI exposes APIs and services as a high-performance relational database, giving you the ability to write SQL-based queries to explore dynamic data. Mods extend Steampipe's capabilities with dashboards, reports, and controls built with simple HCL. The Steampipe CLI is a turnkey solution that includes its own Postgres database, plugin management, and mod support.
+| [Postgres FDW](https://steampipe.io/docs/steampipe_postgres/index) | Steampipe Postgres FDWs are native Postgres Foreign Data Wrappers that translate APIs to foreign tables. Unlike Steampipe CLI, which ships with its own Postgres server instance, the Steampipe Postgres FDWs can be installed in any supported Postgres database version.
+| [SQLite Extension](https://steampipe.io/docs//steampipe_sqlite/index) | Steampipe SQLite Extensions provide SQLite virtual tables that translate your queries into API calls, transparently fetching information from your API or service as you request it.
+| [Export](https://steampipe.io/docs/steampipe_export/index) | Steampipe Plugin Exporters provide a flexible mechanism for exporting information from cloud services and APIs. Each exporter is a stand-alone binary that allows you to extract data using Steampipe plugins without a database.
+| [Turbot Pipes](https://turbot.com/pipes/docs) | Turbot Pipes is the only intelligence, automation & security platform built specifically for DevOps. Pipes provide hosted Steampipe database instances, shared dashboards, snapshots, and more.
+
 ## Developing
 
 Prerequisites:
@@ -84,11 +96,17 @@ Further reading:
 * [Writing plugins](https://steampipe.io/docs/develop/writing-plugins)
 * [Writing your first table](https://steampipe.io/docs/develop/writing-your-first-table)
 
-## Contributing
+## Open Source & Contributing
+
+This repository is published under the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) (source code) and [CC BY-NC-ND](https://creativecommons.org/licenses/by-nc-nd/2.0/) (docs) licenses. Please see our [code of conduct](https://github.com/turbot/.github/blob/main/CODE_OF_CONDUCT.md). We look forward to collaborating with you!
+
+[Steampipe](https://steampipe.io) is a product produced from this open source software, exclusively by [Turbot HQ, Inc](https://turbot.com). It is distributed under our commercial terms. Others are allowed to make their own distribution of the software, but cannot use any of the Turbot trademarks, cloud services, etc. You can learn more in our [Open Source FAQ](https://turbot.com/open-source).
+
+## Get Involved
 
-Please see the [contribution guidelines](https://github.com/turbot/steampipe/blob/main/CONTRIBUTING.md) and our [code of conduct](https://github.com/turbot/steampipe/blob/main/CODE_OF_CONDUCT.md). Contributions to the plugin are subject to the [Apache 2.0 open source license](https://github.com/turbot/steampipe-plugin-github/blob/main/LICENSE).
+**[Join #steampipe on Slack →](https://turbot.com/community/join)**
 
-`help wanted` issues:
+Want to help but don't know where to start? Pick up one of the `help wanted` issues:
 
 * [Steampipe](https://github.com/turbot/steampipe/labels/help%20wanted)
 * [GitHub Plugin](https://github.com/turbot/steampipe-plugin-github/labels/help%20wanted)

docs/index.md

@@ -1,20 +1,21 @@
 ---
-org: Turbot
+organization: Turbot
 category: ["software development"]
 icon_url: "/images/plugins/turbot/github.svg"
 brand_color: "#191717"
 display_name: "GitHub"
-name: "github"
+short_name: "github"
 description: "Steampipe plugin for querying GitHub Repositories, Organizations, and other resources."
-og_description: Use SQL to query repos, orgs and more from GitHub. Open source CLI. No DB required. 
+og_description: "Use SQL to query repos, orgs and more from GitHub. Open source CLI. No DB required."
 og_image: "/images/plugins/turbot/github-social-graphic.png"
+engines: ["steampipe", "sqlite", "postgres", "export"]
 ---
 
 # GitHub + Steampipe
 
-[GitHub](https://www.github.com/) is a provider of Internet hosting for software development and version control using Git. It offers the distributed version control and source code management (SCM) functionality of Git, plus its own features.
+[Steampipe](https://steampipe.io) is an open-source zero-ETL engine to instantly query cloud APIs using SQL.
 
-[Steampipe](https://steampipe.io) is an open source CLI to instantly query cloud APIs using SQL.
+[GitHub](https://www.github.com/) is a provider of Internet hosting for software development and version control using Git. It offers the distributed version control and source code management (SCM) functionality of Git, plus its own features.
 
 For example:
 
@@ -61,7 +62,7 @@ steampipe plugin install github
 | Item        | Description|
 |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Credentials | The GitHub plugin uses a personal access token to authenticate to the GitHub APIs.
-| Permissions | You must create a [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and assign the following scopes:<br />&nbsp;&nbsp;&nbsp;&nbsp;- `repo` (all)<br />&nbsp;&nbsp;&nbsp;&nbsp;- `read:org`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `gist`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `read:user`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `user:email`        
+| Permissions | You must create a [personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) and assign the following scopes:<br />&nbsp;&nbsp;&nbsp;&nbsp;- `repo` (all)<br />&nbsp;&nbsp;&nbsp;&nbsp;- `read:org`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `gist`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `read:user`<br />&nbsp;&nbsp;&nbsp;&nbsp;- `user:email`
 | Radius      | The GitHub plugin query scope is generally the same as the GitHub API. Usually, this means you can list private resources that you have access to, as well as public resources that you own, or that are owned by organizations to which you belong. The same GitHub APIs are used to get information for public resources, but the public items are returned in list calls (because there would be too many). This has an interesting side effect in Steampipe in that you can sometimes query _a specific item_ by _a specific key column or columns_ that does not show up in a list query.<br /><br />For example, `select * from github_my_organization` will list details about all the GitHub Organizations to which you belong. `select * from github_organization where login = 'postgres'` will show you the publicly available details about the `postgres` organization, which didn't show up in your first query! It works this way in Steampipe because [that's how it works in the API](https://docs.github.com/en/rest/reference/orgs#list-organizations-for-a-user). While this may seem counter-intuitive at first, it actually can be quite useful. |
 | Resolution  | 1. Credentials in the Steampipe configuration file (`~/.steampipe/config/github.spc`) <br />2. Credentials specified in environment variables, e.g., `GITHUB_TOKEN`.
 
@@ -86,8 +87,3 @@ connection "github" {
 
 - `token` - [Personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) for your GitHub account. This can also be set via the `GITHUB_TOKEN` environment variable.
 - `base_url` - GitHub Enterprise users have a custom URL location (e.g. `https://github.example.com`). Not required for GitHub cloud. This can also be via the `GITHUB_BASE_URL` environment variable.
-
-## Get involved
-
-- Open source: https://github.com/turbot/steampipe-plugin-github
-- Community: [Join #steampipe on Slack →](https://turbot.com/community/join)

docs/tables/github_actions_artifact.md

@@ -1,14 +1,34 @@
-# Table: github_actions_artifact
+---
+title: "Steampipe Table: github_actions_artifact - Query GitHub Actions Artifacts using SQL"
+description: "Allows users to query GitHub Actions Artifacts, specifically the metadata and download URLs, providing insights into the artifacts generated by GitHub Actions workflows."
+---
 
-Artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact is a file or collection of files produced during a workflow run.
+# Table: github_actions_artifact - Query GitHub Actions Artifacts using SQL
 
-The `github_actions_artifact` table can be used to query information about any artifacts, and **you must specify which repository** in the where or join clause using the `repository_full_name` column.
+GitHub Actions Artifacts are the files created when you build and test your code. These artifacts allow you to persist data after a job has completed, and share that data with another job in the same workflow. An artifact can be a compile output, a log file, a test result, or any other data you want to preserve or share.
+
+## Table Usage Guide
+
+The `github_actions_artifact` table provides insights into artifacts generated by GitHub Actions workflows. As a software developer or DevOps engineer, explore artifact-specific details through this table, including metadata and download URLs. Utilize it to uncover information about artifacts, such as their size, download location, and associated workflow runs.
+
+**Important Notes**
+- You must specify the `repository_full_name` column in `where` or `join` clause to query the table. 
 
 ## Examples
 
 ### List artifacts
+Explore which artifacts are associated with the 'turbot/steampipe' repository on GitHub. This can be useful for developers needing to understand or manage the resources related to this specific project.
+
+```sql+postgres
+select
+  *
+from
+  github_actions_artifact
+where
+  repository_full_name = 'turbot/steampipe';
+```
 
-```sql
+```sql+sqlite
 select
   *
 from
@@ -18,8 +38,22 @@ where
 ```
 
 ### List active artifacts
+Discover the segments that are active artifacts within a specific repository, which is useful in scenarios where you need to track and manage these artifacts for ongoing projects or maintenance tasks. This query enables you to focus on active artifacts, excluding those that have expired, to streamline your artifact management process.
+
+```sql+postgres
+select
+  id,
+  node_id,
+  name,
+  archive_download_url,
+  expired
+from
+  github_actions_artifact
+where
+  repository_full_name = 'turbot/steampipe' and not expired;
+```
 
-```sql
+```sql+sqlite
 select
   id,
   node_id,

docs/tables/github_actions_repository_runner.md

@@ -1,14 +1,34 @@
-# Table: github_actions_repository_runner
+---
+title: "Steampipe Table: github_actions_repository_runner - Query GitHub Actions Repository Runners using SQL"
+description: "Allows users to query GitHub Actions Repository Runners, providing insights into the details of self-hosted runners for a repository."
+---
 
-A runner is a server that runs your workflows when they're triggered. Each runner can run a single job at a time. Self-hosted runners offer more control of hardware, operating system, and software tools than GitHub-hosted runners provide.
+# Table: github_actions_repository_runner - Query GitHub Actions Repository Runners using SQL
 
-The `github_actions_repository_runner` table can be used to query information about any self-hosted runner, and **you must specify which repository** in the where or join clause using the `repository_full_name` column.
+GitHub Actions is a CI/CD service provided by GitHub which allows automating software workflows. It enables developers to build, test, and deploy applications on GitHub, making it easier to integrate changes and deliver better software faster. A key feature of GitHub Actions is the ability to use self-hosted runners, which are servers with GitHub Actions runner application installed.
+
+## Table Usage Guide
+
+The `github_actions_repository_runner` table provides insights into the self-hosted runners of GitHub Actions for a specific repository. As a DevOps engineer, you can explore runner-specific details through this table, including runner IDs, names, operating systems, statuses, and associated metadata. Utilize it to manage and monitor your self-hosted runners, ensuring they are functioning properly and are up-to-date.
+
+**Important Notes**
+- You must specify the `repository_full_name` column in `where` or `join` clause to query the table.
 
 ## Examples
 
 ### List runners
+Explore which runners are associated with the 'turbot/steampipe' repository in GitHub Actions. This can be beneficial for maintaining and managing the performance and efficiency of your workflows.
 
-```sql
+```sql+postgres
+select
+  *
+from
+  github_actions_repository_runner
+where
+  repository_full_name = 'turbot/steampipe';
+```
+
+```sql+sqlite
 select
   *
 from
@@ -18,8 +38,21 @@ where
 ```
 
 ### List runners with mac operating system
+Discover the segments that utilize a Mac operating system within a specific repository. This is beneficial for understanding the distribution of operating systems within your project, which can aid in troubleshooting and optimization efforts.
+
+```sql+postgres
+select
+  repository_full_name,
+  id,
+  name,
+  os
+from
+  github_actions_repository_runner
+where
+  repository_full_name = 'turbot/steampipe' and os = 'macos';
+```
 
-```sql
+```sql+sqlite
 select
   repository_full_name,
   id,
@@ -32,8 +65,22 @@ where
 ```
 
 ### List runners which are in use currently
+This query allows you to identify which runners are currently in use in the specified repository. This can be beneficial for understanding the utilization of resources and managing workflow runs in real-time.
+
+```sql+postgres
+select
+  repository_full_name,
+  id,
+  name,
+  os,
+  busy
+from
+  github_actions_repository_runner
+where
+  repository_full_name = 'turbot/steampipe' and busy;
+```
 
-```sql
+```sql+sqlite
 select
   repository_full_name,
   id,

docs/tables/github_actions_repository_secret.md

@@ -1,14 +1,34 @@
-# Table: github_actions_repository_secret
+---
+title: "Steampipe Table: github_actions_repository_secret - Query GitHub Actions Repository Secrets using SQL"
+description: "Allows users to query GitHub Actions Repository Secrets, specifically to retrieve information about secrets stored in a GitHub repository, providing insights into the security measures in place."
+---
 
-Secrets are encrypted environment variables that you create in an organization.
+# Table: github_actions_repository_secret - Query GitHub Actions Repository Secrets using SQL
 
-The `github_actions_repository_secret` table can be used to query information about any organization secret, and **you must specify which repository** in the where or join clause using the `repository_full_name` column.
+GitHub Actions is a service provided by GitHub that allows you to automate, customize, and execute your software development workflows right in your repository. GitHub Actions makes it easy to automate all your software workflows, now with world-class CI/CD. It enables you to build, test, and deploy your code right from GitHub.
+
+## Table Usage Guide
+
+The `github_actions_repository_secret` table provides insights into secrets stored within a GitHub repository. As a security engineer, explore secret-specific details through this table, including the names of secrets and the dates they were created or updated. Utilize it to uncover information about secrets, such as those that may be outdated or unused, providing a comprehensive view of the repository's security measures.
+
+**Important Notes**
+- You must specify the `repository_full_name` column in `where` or `join` clause to query the table.
 
 ## Examples
 
 ### List secrets
+Explore the hidden aspects of a specific repository within the GitHub Actions environment. This is useful in assessing the security and integrity of the repository.
+
+```sql+postgres
+select
+  *
+from
+  github_actions_repository_secret
+where
+  repository_full_name = 'turbot/steampipe';
+```
 
-```sql
+```sql+sqlite
 select
   *
 from