- What is the Power?
- Setup Instructions
- Contributing to The Power
- Known Issues/Problems/Solutions
- Testcases
- Setting up a GitHub App to use with The Power
- GitHub API Learning Resources
- Scaling to create larger environments
The Power is a simple test framework for GitHub's API's. It's goal is to help you learn to interact with and understand GitHub API's by building test scenarios such as; a repository with a pull request, teams and users on a testing instance of GitHub Enterprise or GitHub.com a pre-existing Organization and Enterprise Account.
The Power can create the following on a blank appliance or organization in <=30 seconds:
- An Organization.
- Users
- A team of users.
- A private repository named testrepo with a branch called new_branch,
- Branch protection rules on branch
main
. - CODEOWNERS file configured for the README.md and
.gitattributes
files. - An Issue with the label
bug
. - A pull request with a code owner requested for review. The pull request contains 2 commits against 2 files and activates the tree view.
- A manifest file for a package manager file with a vulnerability to trigger Dependabot.
- A webhook on testrepo that outputs to it's own smee.io url.
- A Release.
- GitHub Pages configured for testrepo.
- A Gist.
- Mermaid diagrams using create-commit-mermaid.sh to demonstrate the GitHub supported diagram types on the mermaid project.
There are many other features and test-cases you can use or adapt to build scenarios of your own.
Note
The power is not intended as an example of how to write shell scripts.
- Designed to be as simple as possible to understand. To keep things simple we exclusively uses only
curl
andjq
to complete most tasks. Only a few of the more complex scenarios have other dependencies.
There are hundreds of pre-baked scripts to:
- Create commits, secrets, hooks, issue comments, environments.
- Bulk up your appliance by creating hundreds or thousands of users/orgs/repos/teams/pull requests.
- Set up a Tiny GitHub App in less than 1 minute.
- Demonstrate GitHub Actions.
- Demonstrate Code scanning.
You can stitch together scripts to create demos of features or rapidly test a bug or capability.
- The Base Testcase: build-testcase demo of the features of The Power's base test case
build-testcase
. - Push Protection Speed Run a speed run demo of GitHub Push Protection feature.
- Secret Scanning Speed Run creates a repository, enables secret scanning, clones the repository and leaves you ready to commit secrets using build-testcase-secret-scanning.
- GitHub App Commit Signing Demo uses the run-testcase-tiny-app-commit-signing testcase to demonstrate a GitHub App.
The configuration file .gh-api.examples.conf
is the green fuse that drives The Power. The configuration file format is a simple list of key value pairs:
### [Branches](https://docs.github.com/en/rest/commits/commits)
# https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/
proposing-changes-to-your-work-with-pull-requests/about-branches
branch_name="new_branch"
protected_branch_name="main"
required_approving_reviewers=1
required_status_check_name="ci-test/this-check-is-required"
enforce_admins="false"
base_branch=main
The use of kv
pairs in .gh-api-examples.conf
provides maximum flexibility and simplicity. It allows the configuration file to provide the basic descriptors for other more advanced tools like Apache JMeter or hurl
hurl-repo-characteristics.sh shows hurl provisioned with values .gh-api-examples.conf
:
hurl --test --variables-file .gh-api-examples.conf --json hurl-tests/repo-characteristics.hurl | jq -r
The hurl-tests/repo-characteristics
file looks like:
GET {{ GITHUB_API_BASE_URL }}/repos/{{ org }}/{{ repo }}
Accept: application/vnd.github.v3+json
Authorization: token {{ GITHUB_TOKEN }}
HTTP/2 200
[Asserts]
status >= 200
status < 300
header "Content-Type" == "application/json; charset=utf-8"
header "x-github-request-id" isString
jsonpath "$.name" == "{{ repo }}"
jsonpath "$.full_name" == "{{ org}}/{{ repo }}"
There are lots of great tools like JMeter for interacting with API's and building testsuites and many of the latest API's come with their own interactive documentation built-in like the swagger petstore. The Power is a solution for times and places where those tools just aren't available.