code-clerk
v1.1.1
Published
Pulls project metadata from GitHub repositories.
Downloads
5
Readme
Code Clerk
Harvests project metadata from GitHub repositories. The harvested metadata is formatted to make it easy to produce a code.json file for Code.gov.
Installation
Locally:
npm install code-clerk
System-wide:
npm install -g code-clerk
Usage
CLI Usage
First, check out the built-in usage information:
codeclerk --help
Example 1
Assuming:
- Your GitHub access token is in an environment variable named
GITHUB_ACCESS_TOKEN
(the default) - Your agency's acronym is ABC
- Your agency has two GitHub organizations, named AgencyABC and AgencyXYZ
You could get your code.json output by running this command (prints the JSON to your console):
codeclerk ABC AgencyABC AgencyXYZ
Example 2
Assuming:
- Your GitHub access token is in an environment variable named
GITHUB_TOKEN
- Your agency's acronym is XYZ
- Your agency has one GitHub organization, named XYZ
You could get your code.json output by running this command (saves the JSON to a file named code.json
):
codeclerk -t GITHUB_TOKEN -o code.json XYZ XYZ
Basic API Usage
You can easily integrate Code Clerk into your project. Just instantiate a client and run the inventory on your GitHub organization(s). The data returned by the inventory follows the code.json
format.
import { GitHubClient, Inventory } from "code-clerk"
const client = new GitHubClient(YOUR_GITHUB_ACCESS_TOKEN)
const inventory = new Inventory(client, "ABC") // ABC is your agency acronym
const orgs = ["ABC", "AgencyZ"] // List of GitHub organization names
inventory.build(orgs).then((data) => {
console.log(JSON.stringify(data)) // Here's your code.json
})
Advanced API Usage
If you want to customize the way Code Clerk builds your code.json
file, you can do so via transforms and overrides.
Transforms
A transform is simply a JSONata expression that takes a GitHub GraphQL API response and turns it into a format compatible with the Code.gov schema.
You can see the included transforms in src/transforms.js of this package's source code. There are two: defaultGitHubTransform
and minimumGitHubTransform
. The default transform tries to make as much use of GitHub metadata as possible when building your code.json
. The minimum transform only takes the necessary GitHub metadata to build a code.json
that meets the bare minimum specified by the Code.gov schema.
You can write your own transform if the included transforms don't meet your needs. Refer to the JSONata documentation for guidance on how to write JSONata transforms.
To use your custom transform:
const myCustomTransform = `{
(your custom JSONata transform goes here)
}`
const inventory = new Inventory(client, "ABC", { transform: myCustomTransform })
Overrides
An override lets you manually specify a value to use in your repositories' metadata instead of what Code Clerk automatically pulls from the GitHub GraphQL API.
An example of an override is to use a specific contact email for all repositories in your organization instead of the email address listed on the GitHub organization:
const myOverrides = {
contact: {
email: "[email protected]"
}
}
const inventory = new Inventory(client, "ABC", { localOverrides: myOverrides })
Callback
While Code Clerk is building an inventory of your organization's repositories, it can report back some status information on what it is currently processing.
An example would be to print which repository Code Clerk is currently processing:
function myCallback(releaseMetadata, org) {
console.log(`Currently processing repository ${releaseMetadata.name} in the GitHub organization ${org}`)
}
const inventory = new Inventory(client, "ABC", { callback: myCallback })