{"id":18581866,"url":"https://github.com/knative/hack","last_synced_at":"2025-05-16T04:09:14.385Z","repository":{"id":37078447,"uuid":"307744432","full_name":"knative/hack","owner":"knative","description":"Knative common scripts.","archived":false,"fork":false,"pushed_at":"2025-02-17T12:25:57.000Z","size":1887,"stargazers_count":20,"open_issues_count":13,"forks_count":64,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-02-17T13:29:09.211Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knative.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-27T15:27:14.000Z","updated_at":"2025-02-17T12:26:02.000Z","dependencies_parsed_at":"2023-10-10T15:16:18.842Z","dependency_job_id":"0850e95b-0126-4840-8851-86f53a6c2779","html_url":"https://github.com/knative/hack","commit_stats":{"total_commits":281,"total_committers":38,"mean_commits":7.394736842105263,"dds":0.5693950177935942,"last_synced_commit":"e92a16ae08930054adea900534aeb9ea6e5a678f"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knative%2Fhack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knative%2Fhack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knative%2Fhack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knative%2Fhack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knative","download_url":"https://codeload.github.com/knative/hack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239321400,"owners_count":19619697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2024-11-07T00:07:43.985Z","updated_at":"2025-02-17T16:20:14.257Z","avatar_url":"https://github.com/knative.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# knative.dev/hack\n\n`hack` is a collection of scripts used to bootstrap CI processes and other vital\nentrypoint functionality.\n\n## Contributing\n\nIf you are interested in contributing to Knative, take a look at [CLOTRIBUTOR](https://clotributor.dev/search?project=knative\u0026page=1)\nfor a list of help wanted issues across the project.\n\n## Using the `presubmit-tests.sh` helper script\n\nThis is a helper script to run the presubmit tests. To use it:\n\n1. Source this script:\n   ```bash\n   source \"$(go run knative.dev/hack/cmd/script presubmit-tests.sh)\"\n   ```\n\n1. [optional] Define the function `build_tests()`. If you don't define this\n   function, the default action for running the build tests is to:\n\n   - run `go build` on the entire repo\n   - run `hack/verify-codegen.sh` (if it exists)\n   - check licenses in all go packages\n\n1. [optional] Customize the default build test runner, if you're using it. Set\n   the following environment variables if the default values don't fit your\n   needs:\n\n   - `PRESUBMIT_TEST_FAIL_FAST`: Fail the presubmit test immediately if a test\n     fails, defaults to 0 (false).\n\n1. [optional] Define the functions `pre_build_tests()` and/or\n   `post_build_tests()`. These functions will be called before or after the\n   build tests (either your custom one or the default action) and will cause the\n   test to fail if they don't return success.\n\n1. [optional] Define the function `unit_tests()`. If you don't define this\n   function, the default action for running the unit tests is to run all go\n   tests in the repo.\n\n1. [optional] Define the functions `pre_unit_tests()` and/or\n   `post_unit_tests()`. These functions will be called before or after the unit\n   tests (either your custom one or the default action) and will cause the test\n   to fail if they don't return success.\n\n1. [optional] Define the function `integration_tests()`. If you don't define\n   this function, the default action for running the integration tests is to run\n   all run all `./test/e2e-*tests.sh` scripts, in sequence.\n\n1. [optional] Define the functions `pre_integration_tests()` and/or\n   `post_integration_tests()`. These functions will be called before or after\n   the integration tests (either your custom one or the default action) and will\n   cause the test to fail if they don't return success.\n\n1. Call the `main()` function passing `\"$@\"` (with quotes).\n\nRunning the script without parameters, or with the `--all-tests` flag causes all\ntests to be executed, in the right order (i.e., build, then unit, then\nintegration tests).\n\nUse the flags `--build-tests`, `--unit-tests` and `--integration-tests` to run a\nspecific set of tests.\n\nTo run specific programs as a test, use the `--run-test` flag, and provide the\nprogram as the argument. If arguments are required for the program, pass\neverything as a single quotes argument. For example,\n`./presubmit-tests.sh --run-test \"test/my/test data\"`. This flag can be used\nrepeatedly, and each one will be ran in sequential order.\n\nThe script will automatically skip all presubmit tests for PRs where all changed\nfiles are exempt of tests (e.g., a PR changing only the `OWNERS` file).\n\nAlso, for PRs touching only markdown files, the unit and integration tests are\nskipped.\n\n### Sample presubmit test script\n\n```bash\nsource \"$(go run knative.dev/hack/cmd/script presubmit-tests.sh)\"\n\nfunction post_build_tests() {\n  echo \"Cleaning up after build tests\"\n  rm -fr ./build-cache\n}\n\nfunction unit_tests() {\n  make -C tests test\n}\n\nfunction pre_integration_tests() {\n  echo \"Cleaning up before integration tests\"\n  rm -fr ./staging-area\n}\n\n# We use the default integration test runner.\n\nmain \"$@\"\n```\n\n## Using the `e2e-tests.sh` helper script\n\nThis is a helper script for Knative E2E test scripts. To use it:\n\n1. [optional] Customize the test cluster. Pass the flags as described\n   [here](https://github.com/knative/toolbox/blob/main/kntest/pkg/kubetest2/gke/README.md) to the `initialize` function\n   call if the default values don't fit your needs.\n\n1. Source the script:\n    ```bash\n    source \"$(go run knative.dev/hack/cmd/script e2e-tests.sh)\"\n    ```\n\n1. [optional] Write the `knative_setup()` function, which will set up your\n   system under test (e.g., Knative Serving).\n\n1. [optional] Write the `knative_teardown()` function, which will tear down your\n   system under test (e.g., Knative Serving).\n\n1. [optional] Write the `test_setup()` function, which will set up the test\n   resources.\n\n1. [optional] Write the `test_teardown()` function, which will tear down the\n   test resources.\n\n1. [optional] Write the `cluster_setup()` function, which will set up any\n   resources before the test cluster is created.\n\n1. [optional] Write the `cluster_teardown()` function, which will tear down any\n   resources after the test cluster is destroyed.\n\n1. [optional] Write the `dump_extra_cluster_state()` function. It will be called\n   when a test fails, and can dump extra information about the current state of\n   the cluster (typically using `kubectl`).\n\n1. [optional] Write the `on_success` function. It will be called when a test succeeds\n\n1. [optional] Write the `on_failure` function. It will be called when a test fails\n\n1. [optional] Write the `parse_flags()` function. It will be called whenever an\n   unrecognized flag is passed to the script, allowing you to define your own\n   flags. The function must return 0 if the flag is unrecognized, or the number\n   of items to skip in the command line if the flag was parsed successfully. For\n   example, return 1 for a simple flag, and 2 for a flag with a parameter.\n\n1. Call the `initialize()` function passing `\"$@\"`.\n\n1. Write logic for the end-to-end tests. Run all go tests using `go_test_e2e()`\n   (or `report_go_test()` if you need a more fine-grained control) and call\n   `fail_test()` or `success()` if any of them failed. The environment variable\n   `KO_DOCKER_REPO` and `E2E_PROJECT_ID` will be set according to the test\n   cluster.\n\n**Notes:**\n\n1. Calling your script without arguments will create a new cluster in your\n   current GCP project and run the tests against it.\n\n1. Calling your script with `--run-tests` and the variable `KO_DOCKER_REPO` set\n   will immediately start the tests against the cluster currently configured for\n   `kubectl`.\n\n1. By default `knative_teardown()` and `test_teardown()` will be called after\n   the tests finish, use `--skip-teardowns` if you don't want them to be called.\n\n1. By default Google Kubernetes Engine telemetry to Cloud Logging and Monitoring is disabled.\n   This can be enabled by setting `ENABLE_GKE_TELEMETRY` to `true`.\n   \n1. By default Spot Worker nodes are disabled. This can be enabled by setting `ENABLE_PREEMPTIBLE_NODES`\n   to `true`.\n### Sample end-to-end test script\n\nThis script will test that the latest Knative Serving nightly release works. It\ndefines a special flag (`--no-knative-wait`) that causes the script not to wait\nfor Knative Serving to be up before running the tests. It also requires that the\ntest cluster is created in a specific region, `us-west2`.\n\n```bash\nsource \"$(go run knative.dev/hack/cmd/script e2e-tests.sh)\"\n\nfunction knative_setup() {\n  start_latest_knative_serving\n  if (( WAIT_FOR_KNATIVE )); then\n    wait_until_pods_running knative-serving || fail_test \"Knative Serving not up\"\n  fi\n}\n\nfunction parse_flags() {\n  if [[ \"$1\" == \"--no-knative-wait\" ]]; then\n    WAIT_FOR_KNATIVE=0\n    return 1\n  fi\n  return 0\n}\n\nWAIT_FOR_KNATIVE=1\n\n# This test requires a cluster in LA\ninitialize $@ --region=us-west2\n\n# TODO: use go_test_e2e to run the tests.\nkubectl get pods || fail_test\n\nsuccess\n```\n\n## Using the `performance-tests.sh` helper script\n\nThis is a helper script for Knative performance test scripts. In combination\nwith specific Prow jobs, it can automatically manage the environment for running\nbenchmarking jobs for each repo. To use it:\n\n1. Source the script:\n   ```bash\n   source \"$(go run knative.dev/hack/cmd/script performance-tests.sh)\"\n   ```\n\n1. [optional] Customize GCP project settings for the benchmarks. Set the\n   following environment variables if the default value doesn't fit your needs:\n\n   - `PROJECT_NAME`: GCP project name for keeping the clusters that run the\n     benchmarks. Defaults to `knative-performance`.\n   - `SERVICE_ACCOUNT_NAME`: Service account name for controlling GKE clusters\n     and interacting with [Mako](https://github.com/google/mako) server. It MUST\n     have `Kubernetes Engine Admin` and `Storage Admin` role, and be\n     [allowed](https://github.com/google/mako/blob/master/docs/ACCESS.md) by\n     Mako admin. Defaults to `mako-job`.\n\n1. [optional] Customize root path of the benchmarks. This root folder should\n   contain and only contain all benchmarks you want to run continuously. Set the\n   following environment variable if the default value doesn't fit your needs:\n\n   - `BENCHMARK_ROOT_PATH`: Benchmark root path, defaults to\n     `test/performance/benchmarks`. Each repo can decide which folder to put its\n     benchmarks in, and override this environment variable to be the path of\n     that folder.\n\n1. [optional] Write the `update_knative` function, which will update your system\n   under test (e.g. Knative Serving).\n\n1. [optional] Write the `update_benchmark` function, which will update the\n   underlying resources for the benchmark (usually Knative resources and\n   Kubernetes cronjobs for benchmarking). This function accepts a parameter,\n   which is the benchmark name in the current repo.\n\n1. Call the `main()` function with all parameters (e.g. `$@`).\n\n### Sample performance test script\n\nThis script will update `Knative serving` and the given benchmark.\n\n```bash\nsource \"$(go run knative.dev/hack/cmd/script performance-tests.sh)\"\n\nfunction update_knative() {\n  echo \"\u003e\u003e Updating serving\"\n  ko apply -f config/ || abort \"failed to apply serving\"\n}\n\nfunction update_benchmark() {\n  echo \"\u003e\u003e Updating benchmark $1\"\n  ko apply -f ${BENCHMARK_ROOT_PATH}/$1 || abort \"failed to apply benchmark $1\"\n}\n\nmain $@\n```\n\n## Using the `release.sh` helper script\n\nThis is a helper script for Knative release scripts. To use it:\n\n1. Source the script:\n    ```bash\n    source \"$(go run knative.dev/hack/cmd/script release.sh)\"\n    ```\n\n1. [optional] By default, the release script will run\n   `./test/presubmit-tests.sh` as the release validation tests. If you need to\n   run something else, set the environment variable `VALIDATION_TESTS` to the\n   executable to run.\n\n1. Write logic for building the release in a function named `build_release()`.\n   Set the environment variable `ARTIFACTS_TO_PUBLISH` to the list of files\n   created, space separated. Use the following boolean (0 is false, 1 is true)\n   and string environment variables for the logic:\n\n   - `RELEASE_VERSION`: contains the release version if `--version` was passed.\n     This also overrides the value of the `TAG` variable as `v\u003cversion\u003e`.\n   - `RELEASE_BRANCH`: contains the release branch if `--branch` was passed.\n     Otherwise it's empty and `main` HEAD will be considered the release\n     branch.\n   - `RELEASE_NOTES`: contains the filename with the release notes if\n     `--release-notes` was passed. The release notes is a simple markdown file.\n   - `RELEASE_GCS_BUCKET`: contains the GCS bucket name to store the manifests\n     if `--release-gcs` was passed, otherwise the default value\n     `knative-nightly/\u003crepo\u003e` will be used. It is empty if `--publish` was not\n     passed.\n   - `RELEASE_DIR`: contains the directory to store the manifests if\n     `--release-dir` was passed. Defaults to empty value, but if `--nopublish`\n     was passed then points to the repository root directory.\n   - `BUILD_COMMIT_HASH`: the commit short hash for the current repo. If the\n     current git tree is dirty, it will have `-dirty` appended to it.\n   - `BUILD_YYYYMMDD`: current UTC date in `YYYYMMDD` format.\n   - `BUILD_TIMESTAMP`: human-readable UTC timestamp in `YYYY-MM-DD HH:MM:SS`\n     format.\n   - `BUILD_TAG`: a tag in the form `v$BUILD_YYYYMMDD-$BUILD_COMMIT_HASH`.\n   - `KO_DOCKER_REPO`: contains the GCR to store the images if `--release-gcr`\n     was passed, otherwise the default value `gcr.io/knative-nightly` will be\n     used. It is set to `ko.local` if `--publish` was not passed.\n   - `SKIP_TESTS`: true if `--skip-tests` was passed. This is handled\n     automatically.\n   - `TAG_RELEASE`: true if `--tag-release` was passed. In this case, the\n     environment variable `TAG` will contain the release tag in the form\n     `v$BUILD_TAG`.\n   - `PUBLISH_RELEASE`: true if `--publish` was passed. In this case, the\n     environment variable `KO_FLAGS` will be updated with the `-L` option and\n     `TAG` will contain the release tag in the form `v$RELEASE_VERSION`.\n   - `PUBLISH_TO_GITHUB`: true if `--version`, `--branch` and\n     `--publish-release` were passed.\n\n   All boolean environment variables default to false for safety.\n\n   All environment variables above, except `KO_FLAGS`, are marked read-only once\n   `main()` is called (see below).\n\n1. Call the `main()` function passing `\"$@\"` (with quotes).\n\n### Sample release script\n\n```bash\nsource \"$(go run knative.dev/hack/cmd/script release.sh)\"\n\nfunction build_release() {\n  # config/ contains the manifests\n  ko resolve ${KO_FLAGS} -f config/ \u003e release.yaml\n  ARTIFACTS_TO_PUBLISH=\"release.yaml\"\n}\n\nmain \"$@\"\n```\n\n# Origins of `hack`\n\nWhen Kubernetes was first getting started, someone was trying to introduce some\nquick shell scripts and land them into the `./scripts` folder. But there was one\nthat opposed this: Ville Aikas. The compromise was to put those quick scripts in\na folder called `hack` to remind users and developers that there is likely a\nbetter way to perform the task you are attempting that is not using a shell\nscript, like a tested python script.\n\n\u003e \"I was like fine, put them in hack not scripts, cause they are hacks.\" - Ville Aikas\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknative%2Fhack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknative%2Fhack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknative%2Fhack/lists"}