GITHUB WITH SWAMP
Swamp works with GitHub through extensions from the registry. Each extension adds behavior types. A behavior created from one of these types calls GitHub, either through the REST API or through the local gh CLI login. It stores what it finds as Swamp data, which you can query, pass into workflows and keep as a history.
Get started
curl -fsSL https://swamp-club.com/install.sh | sh swamp repo init swamp extension pull @hivemq/github swamp extension pull @hivemq/github/merge swamp extension pull @webframp/githubThe @hivemq/github extension covers security. Its
@hivemq/github/token type audits one token. It records whether the token is
valid, what type it is, which app issued it and which identity it acts as, and
it never stores the token value. The
getting started tutorial runs
a first audit. Three alert types, @hivemq/github/dependabot/alerts,
@hivemq/github/code-scanning/alerts and
@hivemq/github/secret-scanning/alerts, list the open alerts for a set of
repositories in one organization. Each one writes one normalized resource per
repository. A fourth type, @hivemq/github/security-alerts, merges one run of
all three scanners into a Slack Block Kit payload for each repository. It
refuses to build anything if a scanner did not cover every requested repository.
For changes to repositories, @hivemq/github/merge creates and merges pull requests, merges branches, and opens pull requests across several repositories at once. Through the gh CLI it also reads files, commits single-file changes to new branches and opens pull requests from them. Its commitFile and openPullRequest methods support dry runs. @goodcraft/github and its fork @dataverket/github make sure repositories, releases and pull requests exist, and by default they plan before they write. The fork adds methods for the default branch and for verified repository deletion. @webframp/github reads repositories, pull requests, issues, releases and Actions runs through the gh CLI, and it carries out approved triage actions with idempotency keys.
Other extensions cover narrower needs. @keeb/github lists pull requests for one repository. @taylor/github makes sure a single repository exists. @mgreten/stack-status renders the status of stacked pull requests as an HTML flowchart. @mgreten/github-file-track keeps local copies of files tracked in GitHub. @evrardjp/github-local-mirror keeps a local mirror of pull requests, issues and review worktrees for maintainers. The extension reference lists every type, argument and method. Understanding GitHub automation in Swamp discusses how these types fit together with vaults, data and workflows.
GitHub documentation
Getting started with GitHub token audits in Swamp
Pull the @hivemq/github extension, create a token behavior that reads a GitHub token from a file, validate it, and run audit to record the token's identity.
Tutorials →Collect open security alerts across GitHub repositories
Create Dependabot, code scanning and secret scanning alert behaviors with a vaulted token, run their list methods over several repos, and query the results.
How-to Guides →Build Slack payloads from GitHub security alert runs
Run the @hivemq/github/security-alerts build method on three scanner results to write per-repo Slack payloads, and observe the failure on a coverage gap.
How-to Guides →Commit a file change and open a pull request
Use the @hivemq/github/merge behavior to check for an existing pull request, commit one file to a new branch, and open the pull request with dryRun set.
How-to Guides →GitHub extensions
Every Swamp extension for GitHub: behavior types, global arguments, methods, vault configuration and the data each one writes, read from the registry.
Reference →Understanding GitHub automation in Swamp
How GitHub extensions map onto Swamp behaviors, vaults, data and workflows, and the choices teams make about tokens, gh CLI login, dry runs and alert gating.
Explanation →