diff --git a/config/routes.rb b/config/routes.rb
index 1d262438e2..1d38ec41cd 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -9,6 +9,7 @@
get "/docs/api/organizations", to: redirect("/docs/apis/rest-api/organizations")
get "/docs/api/projects", to: redirect("/docs/apis/rest-api/pipelines")
get "/docs/api/*page", to: redirect("/docs/apis/rest-api/%{page}")
+ get "/docs/apis/graphql/cookbooks/packages", to: redirect("/docs/apis/graphql/cookbooks/registries")
get "/docs/apis/graphql-tutorial", to: redirect("/docs/apis/graphql/graphql-tutorial")
get "/docs/apis/graphql", to: redirect("/docs/apis/graphql-api")
get "/docs/apis/graphql/schemas", to: redirect("/docs/apis/graphql-api")
@@ -62,14 +63,17 @@
get "/docs/integrations/sso/g-suite", to: redirect("/docs/integrations/sso/google-workspace")
get "/docs/integrations/sso/cloud-identity", to: redirect("/docs/integrations/sso/g-cloud-identity")
get "/docs/integrations/sso/g-cloud-identity", to: redirect("/docs/integrations/sso/google-workspace-saml")
- get "/docs/packages/manage-repositories", to: redirect("/docs/packages/manage-registries")
- get "/docs/packages/nodejs", to: redirect("/docs/packages/javascript")
+ get "/docs/packages", to: redirect("/docs/package-registries")
+ get "/docs/packages/*page", to: redirect("/docs/package-registries/%{page}")
+ get "/docs/packages/manage-repositories", to: redirect("/docs/package-registries/manage-registries")
+ get "/docs/packages/nodejs", to: redirect("/docs/package-registries/javascript")
+ get "/docs/packages/permissions", to: redirect("/docs/package-registries/security/permissions")
get "/docs/pipelines/emoji", to: redirect("/docs/pipelines/emojis")
get "/docs/pipelines/images-in-log-output", to: redirect("/docs/pipelines/links-and-images-in-log-output")
get "/docs/pipelines/pipelines", to: redirect("/docs/pipelines")
get "/docs/pipelines/ignoring-a-commit", to: redirect("/docs/pipelines/skipping#ignore-a-commit")
get "/docs/pipelines/parallel-builds", to: redirect("/docs/tutorials/parallel-builds")
- get "/docs/pipelines/permissions", to: redirect("/docs/team-management/permissions")
+ get "/docs/pipelines/permissions", to: redirect("/docs/pipelines/security/permissions")
get "/docs/pipelines/plugins", to: redirect("/docs/plugins")
get "/docs/pipelines/uploading-pipelines", to: redirect("/docs/pipelines/defining-steps")
get "/docs/pipelines/security-overview", to: redirect("/docs/pipelines/security/overview")
@@ -81,7 +85,9 @@
get "/docs/quickstart/*page", to: redirect("/docs/tutorials/%{page}")
get "/docs/rest-api", to: redirect("/docs/apis/rest-api")
get "/docs/rest-api/*page", to: redirect("/docs/apis/rest-api/%{page}")
- get "/docs/test-analytics/js-collectors", to: redirect("/docs/test-analytics/javascript-collectors")
+ get "/docs/test-analytics", to: redirect("/docs/test-engine")
+ get "/docs/test-analytics/*page", to: redirect("/docs/test-engine/%{page}")
+ get "/docs/test-analytics/js-collectors", to: redirect("/docs/test-engine/javascript-collectors")
get "/docs/tutorials/gitlab", to: redirect("/docs/integrations/gitlab")
get "/docs/tutorials/github-enterprise", to: redirect("/docs/integrations/github-enterprise")
get "/docs/tutorials/bitbucket", to: redirect("/docs/integrations/bitbucket")
@@ -133,7 +139,7 @@
get "/docs/agent/upgrading", to: redirect("/docs/agent/v3/upgrading", status: 301)
get "/docs/agent/upgrading-to-v3", to: redirect("/docs/agent/v3/upgrading", status: 301)
get "/docs/clusters/queue-metrics", to: redirect("/docs/pipelines/cluster-queue-metrics", status: 301)
- get "/docs/test-analytics/java", to: redirect("/docs/test-analytics/importing-junit-xml", status: 301)
+ get "/docs/test-engine/java", to: redirect("/docs/test-engine/importing-junit-xml", status: 301)
# Old docs routes that we changed around during the development of the v3 agent docs
get "/docs/agent/upgrading-to-v2", to: redirect("/docs/agent/v2/upgrading-to-v2", status: 301)
@@ -143,7 +149,7 @@
get "/docs/agent/v3/agent-meta-data", to: redirect("/docs/agent/v3/cli-start#setting-tags", status: 301)
# Pre GA test analytics
- get "/docs/test-analytics/integrations", to: redirect("/docs/test-analytics", status: 301)
+ get "/docs/test-analytics/integrations", to: redirect("/docs/test-engine", status: 301)
# Quick Reference JSON
get "/docs/quick-reference/pipelines", to: "quick_reference#pipelines", as: :pipelines_quick_reference
diff --git a/data/content/test_analytics_json_fields.schema.yaml b/data/content/test_engine_json_fields.schema.yaml
similarity index 100%
rename from data/content/test_analytics_json_fields.schema.yaml
rename to data/content/test_engine_json_fields.schema.yaml
diff --git a/data/content/test_analytics_json_fields_detail.yaml b/data/content/test_engine_json_fields_detail.yaml
similarity index 100%
rename from data/content/test_analytics_json_fields_detail.yaml
rename to data/content/test_engine_json_fields_detail.yaml
diff --git a/data/content/test_analytics_json_fields_failure_expanded.yaml b/data/content/test_engine_json_fields_failure_expanded.yaml
similarity index 100%
rename from data/content/test_analytics_json_fields_failure_expanded.yaml
rename to data/content/test_engine_json_fields_failure_expanded.yaml
diff --git a/data/content/test_analytics_json_fields_history.yaml b/data/content/test_engine_json_fields_history.yaml
similarity index 100%
rename from data/content/test_analytics_json_fields_history.yaml
rename to data/content/test_engine_json_fields_history.yaml
diff --git a/data/content/test_analytics_json_fields_span.yaml b/data/content/test_engine_json_fields_span.yaml
similarity index 100%
rename from data/content/test_analytics_json_fields_span.yaml
rename to data/content/test_engine_json_fields_span.yaml
diff --git a/data/content/test_analytics_json_fields_test_result.yaml b/data/content/test_engine_json_fields_test_result.yaml
similarity index 94%
rename from data/content/test_analytics_json_fields_test_result.yaml
rename to data/content/test_engine_json_fields_test_result.yaml
index b106c9ee0c..ad0a766857 100644
--- a/data/content/test_analytics_json_fields_test_result.yaml
+++ b/data/content/test_engine_json_fields_test_result.yaml
@@ -4,7 +4,7 @@ fields:
type: UUIDv4 string
enumerated_values:
desc: |
- A unique identifier for this test result. If a test execution with this UUID already exists in the Test Analytics database, this result is ignored.
+ A unique identifier for this test result. If a test execution with this UUID already exists in the Test Engine database, this result is ignored.
examples:
- 1b70486f-ca5f-4e6d-beb8-6347b2e49278
- name: scope
diff --git a/data/content/test_analytics_run_env.schema.yaml b/data/content/test_engine_run_env.schema.yaml
similarity index 100%
rename from data/content/test_analytics_run_env.schema.yaml
rename to data/content/test_engine_run_env.schema.yaml
diff --git a/data/content/test_analytics_run_env.yaml b/data/content/test_engine_run_env.yaml
similarity index 100%
rename from data/content/test_analytics_run_env.yaml
rename to data/content/test_engine_run_env.yaml
diff --git a/data/content/test_splitting_env.yaml b/data/content/test_splitting_env.yaml
index 48cd7ed914..368c3acecf 100644
--- a/data/content/test_splitting_env.yaml
+++ b/data/content/test_splitting_env.yaml
@@ -1,7 +1,7 @@
predefined:
- name: BUILDKITE_BUILD_ID
desc:
- - The UUID of the pipeline build. Test Splitter uses this UUID along with `BUILDKITE_STEP_ID` to uniquely identify the test plan.
+ - The UUID of the pipeline build. The Test Engine Client uses this UUID along with `BUILDKITE_STEP_ID` to uniquely identify the test plan.
- name: BUILDKITE_JOB_ID
desc:
- The UUID of the job in the pipeline's build.
@@ -18,40 +18,90 @@ predefined:
- Ensure you configure `parallelism` in your pipeline definition. Learn more about parallel build steps in [Concurrency and parallelism](https://buildkite.com/docs/pipelines/controlling-concurrency#concurrency-and-parallelism).
- name: BUILDKITE_STEP_ID
desc:
- - The UUID of the step group in the pipeline build. Test Splitter uses this UUID along with `BUILDKITE_BUILD_ID` to uniquely identify the test plan.
+ - The UUID of the step group in the pipeline build. The Test Engine Client uses this UUID along with `BUILDKITE_BUILD_ID` to uniquely identify the test plan.
mandatory:
- - name: BUILDKITE_SPLITTER_API_ACCESS_TOKEN
+ - name: BUILDKITE_TEST_ENGINE_API_ACCESS_TOKEN
desc:
- - Buildkite API access token with `read_suites`, `read_test_plan`, and `write_test_plan` scopes. You can create an [API access token](https://buildkite.com/user/api-access-tokens) from **Personal Settings** > **API Access Tokens** in the Buildkite interface.
- - name: BUILDKITE_SPLITTER_SUITE_SLUG
+ - Buildkite API access token with `read_suites`, `read_test_plan`, and `write_test_plan` scopes. You can create an [API access token](https://buildkite.com/user/api-access-tokens) from **Personal Settings** > **API Access Tokens** in the Buildkite interface. To avoid this token being tied to any one employee or person, ideally, this token should be created for a bot user account within your Buildkite organization.
+ - name: BUILDKITE_TEST_ENGINE_RESULT_PATH
desc:
- - The slug of your Buildkite Test Analytics test suite. You can find the suite slug in the url for your test suite.
+ - The path to store the test result. The Test Engine Client uses this environment variable to tell the runner where to store the test result. The Test Engine Client reads the test result after each test run for retries and verification.
+ - For RSpec, the result is generated using the `--format json` and `--out` CLI options, while for Jest, it is generated using the `--json` and `--outputFile` options. We have included these options in the default test command for RSpec and Jest. If you need to customize your test command, make sure to append the CLI options to save the result to a file.
+ - Please refer to the `BUILDKITE_TEST_ENGINE_TEST_CMD` environment variable for more details.
+ note:
+ - The Test Engine Client will not delete the file after running the test, however it will be deleted by Buildkite Agent as part of the build lifecycle.
+ - name: BUILDKITE_TEST_ENGINE_RUNNER
+ desc:
+ - The test runner to use for running tests. Currently `rspec` and `jest` are supported.
+ - name: BUILDKITE_TEST_ENGINE_SUITE_SLUG
+ desc:
+ - The slug of your Test Engine test suite. You can find the suite slug in the url for your test suite.
- "For example, the slug for the url: `https://buildkite.com/organizations/my-organization/analytics/suites/my-suite` is `my-suite`."
optional:
- - name: BUILDKITE_SPLITTER_DEBUG_ENABLED
- default: false
- desc:
- - A flag to enable more verbose logging.
- - name: BUILDKITE_SPLITTER_RETRY_COUNT
- default: 0
- desc:
- - The number of retries permitted. Test Splitter runs the test command defined in `BUILDKITE_SPLITTER_TEST_CMD`, and retries only the failing tests for a maximum of `BUILDKITE_SPLITTER_RETRY_COUNT` times. For RSpec, the Test Splitter runs `BUILDKITE_SPLITTER_TEST_CMD` with `--only-failures` as the retry command.
- - name: BUILDKITE_SPLITTER_SPLIT_BY_EXAMPLE
- default: false
- desc:
- - A flag to enable split by example. When this option is `true`, the Test Splitter will split the execution of slow test files over multiple partitions.
- - name: BUILDKITE_SPLITTER_TEST_CMD
- default: bundle exec rspec {{testExamples}}
- desc:
- - The test command to run your tests. The Test Splitter will replace and populate the `{{testExamples}}` placeholder with the test plan.
- - name: BUILDKITE_SPLITTER_TEST_FILE_EXCLUDE_PATTERN
- desc:
- - The glob pattern to exclude certain test files or directories. The exclusion will be applied after discovering the test files using a pattern configured with `BUILDKITE_SPLITTER_TEST_FILE_PATTERN`.
- - _This option accepts the pattern syntax supported by the [zzglob](https://github.com/DrJosh9000/zzglob?tab=readme-ov-file#pattern-syntax) library._
- - name: BUILDKITE_SPLITTER_TEST_FILE_PATTERN
- default: spec/**/*_spec.rb
- desc:
- - The glob pattern to discover test files. You can exclude certain test files or directories from the discovered test files using a pattern that can be configured with `BUILDKITE_SPLITTER_TEST_FILE_EXCLUDE_PATTERN`.
- - _This option accepts the pattern syntax supported by the [zzglob](https://github.com/DrJosh9000/zzglob?tab=readme-ov-file#pattern-syntax) library._
+ rspec:
+ - name: BUILDKITE_TEST_ENGINE_DEBUG_ENABLED
+ default: false
+ desc:
+ - A flag to enable more verbose logging.
+ - name: BUILDKITE_TEST_ENGINE_RETRY_CMD
+ desc:
+ - The command to retry the failed tests. The Test Engine Client will replace the `{{testExamples}}` placeholder with the failed tests. If not set, the client will use the same command defined in `BUILDKITE_TEST_ENGINE_TEST_CMD`.
+ - name: BUILDKITE_TEST_ENGINE_RETRY_COUNT
+ default: 0
+ desc:
+ - The number of retries. The Test Engine Client runs the test command defined in `BUILDKITE_TEST_ENGINE_TEST_CMD` and retries only the failed tests up to `BUILDKITE_TEST_ENGINE_RETRY_COUNT` times, using the retry command defined in `BUILDKITE_TEST_ENGINE_RETRY_CMD`.
+ - name: BUILDKITE_TEST_ENGINE_SPLIT_BY_EXAMPLE
+ default: false
+ desc:
+ - A flag to enable split by example. When this option is `true`, the Test Engine Client will split the execution of slow test files over multiple partitions.
+ - name: BUILDKITE_TEST_ENGINE_TEST_CMD
+ default: bundle exec rspec --format progress --format json --out {{resultPath}} {{testExamples}}
+ desc:
+ - The test command to run your tests. The Test Engine Client will replace the `{{testExamples}}` placeholder with the test plan.
+ note:
+ - It is necessary to include `--format json --out {{resultPath}}` in the test command, because the Test Engine Client needs to read the result after each test run.
+ - Please refer to the `BUILDKITE_TEST_ENGINE_RESULT_PATH` environment variable for more details.
+ - name: BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN
+ desc:
+ - The glob pattern to exclude certain test files or directories. The exclusion will be applied after discovering the test files using a pattern configured with `BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN`.
+ - _This option accepts the pattern syntax supported by the [zzglob](https://github.com/DrJosh9000/zzglob?tab=readme-ov-file#pattern-syntax) library._
+ - name: BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN
+ default: spec/**/*_spec.rb
+ desc:
+ - The glob pattern to discover test files. You can exclude certain test files or directories from the discovered test files using a pattern that can be configured with `BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN`.
+ - _This option accepts the pattern syntax supported by the [zzglob](https://github.com/DrJosh9000/zzglob?tab=readme-ov-file#pattern-syntax) library._
+ jest:
+ - name: BUILDKITE_TEST_ENGINE_DEBUG_ENABLED
+ default: false
+ desc:
+ - A flag to enable more verbose logging.
+ - name: BUILDKITE_TEST_ENGINE_RETRY_CMD
+ default: yarn test --testNamePattern '{{testNamePattern}}' --json --testLocationInResults --outputFile {{resultPath}}
+ desc:
+ - The command to retry the failed tests. The Test Engine Client will replace the `{{testNamePattern}}` placeholder with the failed tests.
+ note:
+ - It is necessary to include `--json --testLocationInResults --outputFile {{resultPath}}` in the command, because the Test Engine Client needs to read the result after each test run.
+ - Please refer to the `BUILDKITE_TEST_ENGINE_RESULT_PATH` environment variable for more details.
+ - name: BUILDKITE_TEST_ENGINE_RETRY_COUNT
+ default: 0
+ desc:
+ - The number of retries. The Test Engine Client runs the test command defined in `BUILDKITE_TEST_ENGINE_TEST_CMD` and retries only the failed tests up to `BUILDKITE_TEST_ENGINE_RETRY_COUNT` times, using the retry command defined in `BUILDKITE_TEST_ENGINE_RETRY_CMD`.
+ - name: BUILDKITE_TEST_ENGINE_TEST_CMD
+ default: yarn test {{testExamples}} --json --testLocationInResults --outputFile {{resultPath}}
+ desc:
+ - The test command to run your tests. The Test Engine Client will replace and populate the `{{testExamples}}` placeholder with the test plan.
+ note:
+ - It is necessary to include `--json --testLocationInResults --outputFile {{resultPath}}` in the command, because the Test Engine Client needs to read the result after each test run.
+ - Please refer to the `BUILDKITE_TEST_ENGINE_RESULT_PATH` environment variable for more details.
+ - name: BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN
+ default: "node_modules"
+ desc:
+ - The glob pattern to exclude certain test files or directories. The exclusion will be applied after discovering the test files using a pattern configured with `BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN`.
+ - _This option accepts the pattern syntax supported by the [zzglob](https://github.com/DrJosh9000/zzglob?tab=readme-ov-file#pattern-syntax) library._
+ - name: BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN
+ default: "**/{__tests__/**/*,*.spec,*.test}.{ts,js,tsx,jsx}"
+ desc:
+ - The glob pattern to discover test files. You can exclude certain test files or directories from the discovered test files using a pattern that can be configured with `BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN`.
+ - _This option accepts the pattern syntax supported by the [zzglob](https://github.com/DrJosh9000/zzglob?tab=readme-ov-file#pattern-syntax) library._
diff --git a/data/nav.yml b/data/nav.yml
index e2902b65f1..aaaf21fda4 100644
--- a/data/nav.yml
+++ b/data/nav.yml
@@ -356,24 +356,8 @@
path: "pipelines/security/oidc"
- name: "OIDC with AWS"
path: "pipelines/security/oidc/aws"
- - name: "CLI"
- children:
- - name: "Overview"
- path: "cli"
- - name: "Installation"
- path: "cli/installation"
- - name: "Configuration"
- path: "cli/configuration"
- - name: "Team management"
- children:
- - name: "Overview"
- path: "team-management"
- - name: "User and team permissions"
- path: "team-management/permissions"
- - name: "Enforce 2FA"
- path: "team-management/enforce-2fa"
- - name: "System banners"
- path: "team-management/system-banners"
+ - name: "Permissions"
+ path: "pipelines/security/permissions"
- name: "Governance"
children:
- name: "Overview"
@@ -396,131 +380,209 @@
path: "pipelines/waterfall"
- name: "Cluster queue metrics"
path: "pipelines/cluster-queue-metrics"
- pill: "beta"
-- name: "Test Analytics"
- path: "test-analytics"
+ - name: "Integrations"
+ children:
+ - name: "Overview"
+ path: "integrations"
+ - name: "Plugins"
+ children:
+ - name: "Overview"
+ path: "plugins"
+ - name: "Using plugins"
+ path: "plugins/using"
+ - name: "Plugins directory"
+ path: "plugins/directory"
+ - name: "Plugin tools"
+ path: "plugins/tools"
+ - name: "Writing plugins"
+ path: "plugins/writing"
+ - name: "Other integrations"
+ children:
+ - name: "Amazon EventBridge"
+ path: "integrations/amazon-eventbridge"
+ - name: "Artifactory"
+ path: "integrations/artifactory"
+ - name: "Build status badges"
+ path: "integrations/build-status-badges"
+ - name: "CCMenu & CCTray"
+ path: "integrations/cc-menu"
+ - name: "Docker Hub"
+ path: "integrations/docker-hub"
+ - name: "PagerDuty"
+ path: "integrations/pagerduty"
+ - name: "Slack"
+ path: "integrations/slack"
+- name: "Test Engine"
+ path: "test-engine"
children:
- name: "Overview"
- path: "test-analytics"
+ path: "test-engine"
- name: "Getting started"
start_expanded: true
children:
- name: "Configuring test suites"
- path: "test-analytics/test-suites"
- - name: "Configuring test splitting"
- path: "test-analytics/test-splitting"
+ path: "test-engine/test-suites"
- name: "Permissions"
- path: "test-analytics/permissions"
+ path: "test-engine/permissions"
- name: "CI environment variables"
- path: "test-analytics/ci-environments"
- - name: "Test executions"
- path: "test-analytics/test-executions"
+ path: "test-engine/ci-environments"
- name: "Public test suites"
- path: "test-analytics/public-test-suites"
+ path: "test-engine/public-test-suites"
- name: "Test ownership"
- pill: "beta"
- path: "test-analytics/test-ownership"
+ path: "test-engine/test-ownership"
- name: "Flaky test assignment"
- path: "test-analytics/flaky-test-assignment"
- - name: "Languages"
+ path: "test-engine/flaky-test-assignment"
+ - name: "Usage and billing"
+ path: "test-engine/usage-and-billing"
+ - name: "Test splitting"
start_expanded: true
+ children:
+ - name: "Overview"
+ path: "test-engine/test-splitting"
+ - name: "Configuring"
+ path: "test-engine/test-splitting/configuring"
+ - name: "Test Engine Client installation"
+ path: "test-engine/test-splitting/client-installation"
+ - name: "Languages"
children:
- name: "Ruby"
- path: "test-analytics/ruby-collectors"
+ path: "test-engine/ruby-collectors"
- name: "JavaScript"
- path: "test-analytics/javascript-collectors"
+ path: "test-engine/javascript-collectors"
- name: "Swift"
- path: "test-analytics/swift-collectors"
+ path: "test-engine/swift-collectors"
- name: "Android"
- path: "test-analytics/android-collectors"
+ path: "test-engine/android-collectors"
- name: "Python"
- path: "test-analytics/python-collectors"
+ path: "test-engine/python-collectors"
- name: "Go"
- path: "test-analytics/golang-collectors"
+ path: "test-engine/golang-collectors"
- name: ".NET"
- path: "test-analytics/dotnet-collectors"
+ path: "test-engine/dotnet-collectors"
- name: "Elixir"
- path: "test-analytics/elixir-collectors"
+ path: "test-engine/elixir-collectors"
- name: "Rust"
- path: "test-analytics/rust-collectors"
+ path: "test-engine/rust-collectors"
- name: "Java"
- path: "test-analytics/java"
+ path: "test-engine/java"
- name: "Other languages"
- path: "test-analytics/other-collectors"
+ path: "test-engine/other-collectors"
- name: "References"
- start_expanded: true
children:
- name: "Importing JUnit XML"
- path: "test-analytics/importing-junit-xml"
+ path: "test-engine/importing-junit-xml"
- name: "Importing JSON"
- path: "test-analytics/importing-json"
+ path: "test-engine/importing-json"
- name: "Writing your own collectors"
- path: "test-analytics/your-own-collectors"
-- name: "Packages"
- path: "packages"
+ path: "test-engine/your-own-collectors"
+- name: "Package Registries"
+ path: "package-registries"
children:
- name: "Overview"
- path: "packages"
+ path: "package-registries"
- name: "Introduction"
start_expanded: true
children:
- name: "Background"
- path: "packages/background"
+ path: "package-registries/background"
- name: "Getting started"
- path: "packages/getting-started"
- - name: "Registries"
- start_expanded: true
- children:
- - name: "Manage registries"
- path: "packages/manage-registries"
- - name: "Private storage"
- path: "packages/private-storage"
- - name: "Security"
- start_expanded: true
- children:
- - name: "Overview"
- path: "packages/security"
- - name: "OIDC"
- path: "packages/security/oidc"
+ path: "package-registries/getting-started"
+ - name: "Registries"
+ children:
+ - name: "Manage registries"
+ path: "package-registries/manage-registries"
+ - name: "Private storage"
+ path: "package-registries/private-storage"
+ - name: "Security"
+ children:
+ - name: "Overview"
+ path: "package-registries/security"
+ - name: "OIDC"
+ path: "package-registries/security/oidc"
- name: "Permissions"
- path: "packages/permissions"
+ path: "package-registries/security/permissions"
- name: "Package ecosystems"
- start_expanded: true
children:
- name: "Overview"
- path: "packages/ecosystems"
+ path: "package-registries/ecosystems"
- name: "Alpine"
- path: "packages/alpine"
+ path: "package-registries/alpine"
- name: "Container"
- path: "packages/container"
+ path: "package-registries/container"
- name: "Debian"
- path: "packages/debian"
+ path: "package-registries/debian"
- name: "Files"
- path: "packages/files"
+ path: "package-registries/files"
- name: "Helm"
start_expanded: true
children:
- name: "OCI-based"
- path: "packages/helm-oci"
+ path: "package-registries/helm-oci"
- name: "Standard"
- path: "packages/helm"
+ path: "package-registries/helm"
- name: "Java"
start_expanded: true
children:
- name: "Maven"
- path: "packages/maven"
+ path: "package-registries/maven"
- name: "Gradle"
- path: "packages/gradle"
+ path: "package-registries/gradle"
- name: "JavaScipt"
- path: "packages/javascript"
+ path: "package-registries/javascript"
- name: "Python"
- path: "packages/python"
+ path: "package-registries/python"
- name: "Red Hat"
- path: "packages/red-hat"
+ path: "package-registries/red-hat"
- name: "Ruby"
- path: "packages/ruby"
+ path: "package-registries/ruby"
- name: "Terraform"
- path: "packages/terraform"
+ path: "package-registries/terraform"
+- name: "Platform"
+ path: "platform"
+ children:
+ - name: "Overview"
+ path: "platform"
+ - name: "Team management"
+ start_expanded: true
+ children:
+ - name: "Overview"
+ path: "team-management"
+ - name: "User and team permissions"
+ path: "team-management/permissions"
+ - name: "Enforce 2FA"
+ path: "team-management/enforce-2fa"
+ - name: "System banners"
+ path: "team-management/system-banners"
+ - name: "CLI"
+ children:
+ - name: "Overview"
+ path: "cli"
+ - name: "Installation"
+ path: "cli/installation"
+ - name: "Configuration"
+ path: "cli/configuration"
+ - name: "SSO"
+ children:
+ - name: "Overview"
+ path: "integrations/sso"
+ - name: "Okta"
+ path: "integrations/sso/okta"
+ - name: "ADFS"
+ path: "integrations/sso/adfs"
+ - name: "Google Workspace"
+ path: "integrations/sso/google-workspace"
+ - name: "Google Workspace (SAML)"
+ path: "integrations/sso/google-workspace-saml"
+ - name: "GitHub"
+ path: "integrations/sso/github-sso"
+ - name: "OneLogin"
+ path: "integrations/sso/onelogin"
+ - name: "Azure AD"
+ path: "integrations/sso/azure-ad"
+ - name: "Custom SAML"
+ path: "integrations/sso/custom-saml"
+ - name: "Set up with GraphQL"
+ path: "integrations/sso/sso-setup-with-graphql"
- name: "APIs"
path: "apis"
children:
@@ -542,33 +604,22 @@
path: "apis/agent-api"
- name: "Metrics"
path: "apis/agent-api/metrics"
- - name: "Analytics"
- children:
- - name: "Flaky tests"
- path: "apis/rest-api/analytics/flaky-tests"
- - name: "Runs"
- path: "apis/rest-api/analytics/runs"
- - name: "Suites"
- path: "apis/rest-api/analytics/suites"
- - name: "Tests"
- path: "apis/rest-api/analytics/tests"
- name: "Organizations"
children:
- name: "Overview"
path: "apis/rest-api/organizations"
- name: "Members"
path: "apis/rest-api/organizations/members"
- pill: "beta"
- - name: "Packages "
+ - name: "Package Registries "
# Keep space at end to prevent "Packages" in global nav bar being
# highlighted when any child page of "API > REST > Packages" is selected.
children:
- name: "Registries"
- path: "apis/rest-api/packages/registries"
+ path: "apis/rest-api/package-registries/registries"
- name: "Registry tokens"
- path: "apis/rest-api/packages/registry-tokens"
+ path: "apis/rest-api/package-registries/registry-tokens"
- name: "Packages"
- path: "apis/rest-api/packages/packages"
+ path: "apis/rest-api/package-registries/packages"
- name: "Pipelines "
# Keep space at end to prevent "Pipelines" in global nav bar being
# highlighted when any child page of "API > REST > Pipelines" is selected.
@@ -600,7 +651,6 @@
- name: "User"
path: "apis/rest-api/user"
- name: "Teams"
- pill: "beta"
children:
- name: "Overview"
path: "apis/rest-api/teams"
@@ -610,6 +660,18 @@
path: "apis/rest-api/teams/pipelines"
- name: "Suites"
path: "apis/rest-api/teams/suites"
+ - name: "Test Engine "
+ # Keep space at end to prevent "Test Engine" in global nav bar being
+ # highlighted when any child page of "API > REST > Pipelines" is selected.
+ children:
+ - name: "Flaky tests"
+ path: "apis/rest-api/test-engine/flaky-tests"
+ - name: "Runs"
+ path: "apis/rest-api/test-engine/runs"
+ - name: "Suites"
+ path: "apis/rest-api/test-engine/suites"
+ - name: "Tests"
+ path: "apis/rest-api/test-engine/tests"
- name: "GraphQL"
children:
- name: Overview
@@ -630,12 +692,12 @@
path: apis/graphql/cookbooks/clusters
- name: Jobs
path: apis/graphql/cookbooks/jobs
- - name: Packages
- path: apis/graphql/cookbooks/packages
- name: Pipelines
path: apis/graphql/cookbooks/pipelines
- name: Pipeline templates
path: apis/graphql/cookbooks/pipeline-templates
+ - name: Registries
+ path: apis/graphql/cookbooks/registries
- name: Rules
path: apis/graphql/cookbooks/rules
- name: Organizations
@@ -644,7 +706,6 @@
path: apis/graphql/cookbooks/teams
- name: Limits
path: apis/graphql/graphql-resource-limits
-
- name: "Webhooks"
children:
- name: "Overview"
@@ -661,56 +722,3 @@
path: "apis/webhooks/ping-events"
- name: "Integrations"
path: "apis/webhooks/integrations"
-- name: "Integrations"
- path: "integrations"
- children:
- - name: "Overview"
- path: "integrations"
- - name: "Plugins"
- children:
- - name: "Overview"
- path: "plugins"
- - name: "Using plugins"
- path: "plugins/using"
- - name: "Plugins directory"
- path: "plugins/directory"
- - name: "Plugin tools"
- path: "plugins/tools"
- - name: "Writing plugins"
- path: "plugins/writing"
- - name: "SSO"
- children:
- - name: "Overview"
- path: "integrations/sso"
- - name: "Okta"
- path: "integrations/sso/okta"
- - name: "ADFS"
- path: "integrations/sso/adfs"
- - name: "Google Workspace"
- path: "integrations/sso/google-workspace"
- - name: "Google Workspace (SAML)"
- path: "integrations/sso/google-workspace-saml"
- - name: "GitHub"
- path: "integrations/sso/github-sso"
- - name: "OneLogin"
- path: "integrations/sso/onelogin"
- - name: "Azure AD"
- path: "integrations/sso/azure-ad"
- - name: "Custom SAML"
- path: "integrations/sso/custom-saml"
- - name: "Set up with GraphQL"
- path: "integrations/sso/sso-setup-with-graphql"
- - name: "Amazon EventBridge"
- path: "integrations/amazon-eventbridge"
- - name: "Artifactory"
- path: "integrations/artifactory"
- - name: "Build status badges"
- path: "integrations/build-status-badges"
- - name: "CCMenu & CCTray"
- path: "integrations/cc-menu"
- - name: "Docker Hub"
- path: "integrations/docker-hub"
- - name: "PagerDuty"
- path: "integrations/pagerduty"
- - name: "Slack"
- path: "integrations/slack"
diff --git a/data/tiles.yml b/data/tiles.yml
index f120f99eb3..20c15e4f05 100644
--- a/data/tiles.yml
+++ b/data/tiles.yml
@@ -1,46 +1,49 @@
---
-test_analytics_features:
+test_engine_features:
- title: "Deep performance analysis"
- url: "/docs/test-analytics/test-suites#trends-and-analysis"
+ url: "/docs/test-engine/test-suites#trends-and-analysis"
desc: "Automatic tracing across your test suite, deeply integrated with your programming language and test framework."
- title: "Find and fix flaky tests"
- url: "/docs/test-analytics/test-suites#detecting-flaky-tests"
+ url: "/docs/test-engine/test-suites#detecting-flaky-tests"
desc: "Quickly identify which tests are the most disruptive for your team, and get a head-start on fixing them."
-test_analytics_guides:
+ - title: "Reduce build times with test splitting"
+ url: "/docs/test-engine/test-splitting"
+ desc: "Split tests evenly across agents to reduce overall pipeline build times, especially for highly complex test suites."
+test_engine_guides:
- title: "Languages"
links:
- text: "Ruby"
- url: "/docs/test-analytics/ruby-collectors"
+ url: "/docs/test-engine/ruby-collectors"
- text: "JavaScript"
- url: "/docs/test-analytics/javascript-collectors"
+ url: "/docs/test-engine/javascript-collectors"
- text: "Swift"
- url: "/docs/test-analytics/swift-collectors"
+ url: "/docs/test-engine/swift-collectors"
- text: "Android"
- url: "/docs/test-analytics/android-collectors"
+ url: "/docs/test-engine/android-collectors"
- text: "Python"
- url: "/docs/test-analytics/python-collectors"
+ url: "/docs/test-engine/python-collectors"
- text: "Go"
- url: "/docs/test-analytics/golang-collectors"
+ url: "/docs/test-engine/golang-collectors"
- text: ".NET"
- url: "/docs/test-analytics/dotnet-collectors"
+ url: "/docs/test-engine/dotnet-collectors"
- text: "Elixir"
- url: "/docs/test-analytics/elixir-collectors"
+ url: "/docs/test-engine/elixir-collectors"
- text: "Rust"
- url: "/docs/test-analytics/rust-collectors"
+ url: "/docs/test-engine/rust-collectors"
- text: "Java"
- url: "/docs/test-analytics/java"
+ url: "/docs/test-engine/java"
- text: "Other languages"
- url: "/docs/test-analytics/other-collectors"
+ url: "/docs/test-engine/other-collectors"
- title: "References"
links:
- text: "Uploading JSON data"
- url: "/docs/test-analytics/importing-json"
+ url: "/docs/test-engine/importing-json"
- text: "Uploading JUnit XML results"
- url: "/docs/test-analytics/importing-junit-xml"
+ url: "/docs/test-engine/importing-junit-xml"
- text: "Build your own collector"
- url: "/docs/test-analytics/your-own-collectors"
+ url: "/docs/test-engine/your-own-collectors"
- text: "CI environment variables"
- url: "/docs/test-analytics/ci-environments"
+ url: "/docs/test-engine/ci-environments"
- ""
integrations:
- title: "Plugins"
@@ -57,28 +60,6 @@ integrations:
url: "/docs/plugins/tools"
- text: "Writing Plugins"
url: "/docs/plugins/writing"
- - title: "SSO"
- desc: "You can use a single sign-on (SSO) provider to protect access to your organization's data in Buildkite. Buildkite supports many different SSO providers."
- url: "/docs/integrations/sso"
- links:
- - text: "Okta"
- url: "/docs/integrations/sso/okta"
- - text: "ADFS"
- url: "/docs/integrations/sso/adfs"
- - text: "Google Workspace"
- url: "/docs/integrations/sso/google-workspace"
- - text: "Google Workspace (SAML)"
- url: "/docs/integrations/sso/google-workspace-saml"
- - text: "GitHub"
- url: "/docs/integrations/sso/github-sso"
- - text: "OneLogin"
- url: "/docs/integrations/sso/onelogin"
- - text: "Azure AD"
- url: "/docs/integrations/sso/azure-ad"
- - text: "Custom SAML"
- url: "/docs/integrations/sso/custom-saml"
- - text: "Setup with GraphQL"
- url: "/docs/integrations/sso/sso-setup-with-graphql"
- title: "Other integrations"
desc: "Buildkite offers other integrations to improve your workflow."
links:
diff --git a/images/docs/home/package_registries.png b/images/docs/home/package_registries.png
new file mode 100644
index 0000000000..29a708ab84
Binary files /dev/null and b/images/docs/home/package_registries.png differ
diff --git a/images/docs/home/package_registries.svg b/images/docs/home/package_registries.svg
new file mode 100644
index 0000000000..9f277746f4
--- /dev/null
+++ b/images/docs/home/package_registries.svg
@@ -0,0 +1,58 @@
+
diff --git a/images/docs/home/pipelines.png b/images/docs/home/pipelines.png
new file mode 100644
index 0000000000..186a5dbbed
Binary files /dev/null and b/images/docs/home/pipelines.png differ
diff --git a/images/docs/home/pipelines.svg b/images/docs/home/pipelines.svg
index 547b4645b2..3769fc9a7a 100644
--- a/images/docs/home/pipelines.svg
+++ b/images/docs/home/pipelines.svg
@@ -1 +1,49 @@
-
\ No newline at end of file
+
diff --git a/images/docs/home/test_analytics.svg b/images/docs/home/test_analytics.svg
deleted file mode 100644
index 4abd0ce9c6..0000000000
--- a/images/docs/home/test_analytics.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/images/docs/home/test_engine.png b/images/docs/home/test_engine.png
new file mode 100644
index 0000000000..d1d00169a9
Binary files /dev/null and b/images/docs/home/test_engine.png differ
diff --git a/images/docs/home/test_engine.svg b/images/docs/home/test_engine.svg
new file mode 100644
index 0000000000..255d8a54e9
--- /dev/null
+++ b/images/docs/home/test_engine.svg
@@ -0,0 +1,46 @@
+
diff --git a/images/docs/test_analytics/flaky_test_assignment/flaky-test-no-teams.png b/images/docs/test_engine/flaky_test_assignment/flaky-test-no-teams.png
similarity index 100%
rename from images/docs/test_analytics/flaky_test_assignment/flaky-test-no-teams.png
rename to images/docs/test_engine/flaky_test_assignment/flaky-test-no-teams.png
diff --git a/images/docs/test_analytics/flaky_test_assignment/flaky-test-summary-mailer.png b/images/docs/test_engine/flaky_test_assignment/flaky-test-summary-mailer.png
similarity index 100%
rename from images/docs/test_analytics/flaky_test_assignment/flaky-test-summary-mailer.png
rename to images/docs/test_engine/flaky_test_assignment/flaky-test-summary-mailer.png
diff --git a/images/docs/test_analytics/flaky_test_assignment/flaky-test-teams.png b/images/docs/test_engine/flaky_test_assignment/flaky-test-teams.png
similarity index 100%
rename from images/docs/test_analytics/flaky_test_assignment/flaky-test-teams.png
rename to images/docs/test_engine/flaky_test_assignment/flaky-test-teams.png
diff --git a/images/docs/test_analytics/flaky_test_assignment/outdated-assignments.png b/images/docs/test_engine/flaky_test_assignment/outdated-assignments.png
similarity index 100%
rename from images/docs/test_analytics/flaky_test_assignment/outdated-assignments.png
rename to images/docs/test_engine/flaky_test_assignment/outdated-assignments.png
diff --git a/images/docs/test_analytics/flaky_test_assignment/recent-assignments.png b/images/docs/test_engine/flaky_test_assignment/recent-assignments.png
similarity index 100%
rename from images/docs/test_analytics/flaky_test_assignment/recent-assignments.png
rename to images/docs/test_engine/flaky_test_assignment/recent-assignments.png
diff --git a/images/docs/test_analytics/flaky_test_assignment/team-settings.png b/images/docs/test_engine/flaky_test_assignment/team-settings.png
similarity index 100%
rename from images/docs/test_analytics/flaky_test_assignment/team-settings.png
rename to images/docs/test_engine/flaky_test_assignment/team-settings.png
diff --git a/images/docs/test_analytics/icon-find-flaky-tests.svg b/images/docs/test_engine/icon-find-flaky-tests.svg
similarity index 100%
rename from images/docs/test_analytics/icon-find-flaky-tests.svg
rename to images/docs/test_engine/icon-find-flaky-tests.svg
diff --git a/images/docs/test_analytics/icon-monitoring.svg b/images/docs/test_engine/icon-monitoring.svg
similarity index 100%
rename from images/docs/test_analytics/icon-monitoring.svg
rename to images/docs/test_engine/icon-monitoring.svg
diff --git a/images/docs/test_analytics/icon-performance-analysis.svg b/images/docs/test_engine/icon-performance-analysis.svg
similarity index 100%
rename from images/docs/test_analytics/icon-performance-analysis.svg
rename to images/docs/test_engine/icon-performance-analysis.svg
diff --git a/images/docs/test_analytics/monitors/monitors.png b/images/docs/test_engine/monitors/monitors.png
similarity index 100%
rename from images/docs/test_analytics/monitors/monitors.png
rename to images/docs/test_engine/monitors/monitors.png
diff --git a/images/docs/test_analytics/overview.png b/images/docs/test_engine/overview.png
similarity index 100%
rename from images/docs/test_analytics/overview.png
rename to images/docs/test_engine/overview.png
diff --git a/images/docs/test_analytics/permissions/team-section-list.png b/images/docs/test_engine/permissions/team-section-list.png
similarity index 100%
rename from images/docs/test_analytics/permissions/team-section-list.png
rename to images/docs/test_engine/permissions/team-section-list.png
diff --git a/images/docs/test_analytics/permissions/team-section-test-suites-list.png b/images/docs/test_engine/permissions/team-section-test-suites-list.png
similarity index 100%
rename from images/docs/test_analytics/permissions/team-section-test-suites-list.png
rename to images/docs/test_engine/permissions/team-section-test-suites-list.png
diff --git a/images/docs/test_analytics/permissions/user-section-teams-list.png b/images/docs/test_engine/permissions/user-section-teams-list.png
similarity index 100%
rename from images/docs/test_analytics/permissions/user-section-teams-list.png
rename to images/docs/test_engine/permissions/user-section-teams-list.png
diff --git a/images/docs/test_analytics/public_test_suites/security.png b/images/docs/test_engine/public_test_suites/security.png
similarity index 100%
rename from images/docs/test_analytics/public_test_suites/security.png
rename to images/docs/test_engine/public_test_suites/security.png
diff --git a/images/docs/test_analytics/public_test_suites/settings.png b/images/docs/test_engine/public_test_suites/settings.png
similarity index 100%
rename from images/docs/test_analytics/public_test_suites/settings.png
rename to images/docs/test_engine/public_test_suites/settings.png
diff --git a/images/docs/test_analytics/ruby_collectors/annotation-span.png b/images/docs/test_engine/ruby_collectors/annotation-span.png
similarity index 100%
rename from images/docs/test_analytics/ruby_collectors/annotation-span.png
rename to images/docs/test_engine/ruby_collectors/annotation-span.png
diff --git a/images/docs/test_analytics/ruby_collectors/execution-prefix-suffix.png b/images/docs/test_engine/ruby_collectors/execution-prefix-suffix.png
similarity index 100%
rename from images/docs/test_analytics/ruby_collectors/execution-prefix-suffix.png
rename to images/docs/test_engine/ruby_collectors/execution-prefix-suffix.png
diff --git a/images/docs/test_analytics/test_ownership/test-ownership.png b/images/docs/test_engine/test_ownership/test-ownership.png
similarity index 100%
rename from images/docs/test_analytics/test_ownership/test-ownership.png
rename to images/docs/test_engine/test_ownership/test-ownership.png
diff --git a/images/docs/test_engine/test_splitting/setup-page-summary.png b/images/docs/test_engine/test_splitting/setup-page-summary.png
new file mode 100644
index 0000000000..7f91222139
Binary files /dev/null and b/images/docs/test_engine/test_splitting/setup-page-summary.png differ
diff --git a/images/docs/test_analytics/test_suites/execution-issues.png b/images/docs/test_engine/test_suites/execution-issues.png
similarity index 100%
rename from images/docs/test_analytics/test_suites/execution-issues.png
rename to images/docs/test_engine/test_suites/execution-issues.png
diff --git a/images/docs/test_analytics/test_suites/run-issues.png b/images/docs/test_engine/test_suites/run-issues.png
similarity index 100%
rename from images/docs/test_analytics/test_suites/run-issues.png
rename to images/docs/test_engine/test_suites/run-issues.png
diff --git a/images/docs/test_analytics/test_suites/span-timeline.png b/images/docs/test_engine/test_suites/span-timeline.png
similarity index 100%
rename from images/docs/test_analytics/test_suites/span-timeline.png
rename to images/docs/test_engine/test_suites/span-timeline.png
diff --git a/images/docs/test_analytics/test_suites/test-execution-stats.png b/images/docs/test_engine/test_suites/test-execution-stats.png
similarity index 100%
rename from images/docs/test_analytics/test_suites/test-execution-stats.png
rename to images/docs/test_engine/test_suites/test-execution-stats.png
diff --git a/images/docs/test_analytics/test_suites/test-stats.png b/images/docs/test_engine/test_suites/test-stats.png
similarity index 100%
rename from images/docs/test_analytics/test_suites/test-stats.png
rename to images/docs/test_engine/test_suites/test-stats.png
diff --git a/images/docs/test_analytics/test_suites/test-trendx.png b/images/docs/test_engine/test_suites/test-trendx.png
similarity index 100%
rename from images/docs/test_analytics/test_suites/test-trendx.png
rename to images/docs/test_engine/test_suites/test-trendx.png
diff --git a/images/docs/test_analytics/test_executions/test_executions.png b/images/docs/test_engine/usage_and_billing/test_executions.png
similarity index 100%
rename from images/docs/test_analytics/test_executions/test_executions.png
rename to images/docs/test_engine/usage_and_billing/test_executions.png
diff --git a/pages/agent/v3/cli_oidc.md b/pages/agent/v3/cli_oidc.md
index cfe74b0c46..8baaf5612b 100644
--- a/pages/agent/v3/cli_oidc.md
+++ b/pages/agent/v3/cli_oidc.md
@@ -7,7 +7,7 @@ Refer to the following documentation for more information:
- The [What is OpenID Connect](https://openid.net/developers/how-connect-works/) overview on the OpenID web site for more details about how OIDC works.
- The [OpenID Connect Core documentation](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) for more information about how OIDC tokens are constructed and how to extract and use claims.
-Learn more about how to restrict your Buildkite Agents' access to deployment environments like AWS, from the OIDC in [Buildkite Pipelines](/docs/pipelines/security/oidc) and with [AWS](/docs/pipelines/security/oidc/aws) documentation pages, as well as the [Buildkite Packages](/docs/packages/security/oidc) documentation page.
+Learn more about how to restrict your Buildkite Agents' access to deployment environments like AWS, from the OIDC in [Buildkite Pipelines](/docs/pipelines/security/oidc) and with [AWS](/docs/pipelines/security/oidc/aws) documentation pages, as well as the [Buildkite Package Registries](/docs/package-registries/security/oidc) documentation page.
## Request OIDC token
diff --git a/pages/apis/graphql/cookbooks/packages.md b/pages/apis/graphql/cookbooks/registries.md
similarity index 85%
rename from pages/apis/graphql/cookbooks/packages.md
rename to pages/apis/graphql/cookbooks/registries.md
index b119108a96..b22affcd9a 100644
--- a/pages/apis/graphql/cookbooks/packages.md
+++ b/pages/apis/graphql/cookbooks/registries.md
@@ -1,6 +1,6 @@
-# Packages
+# Registries
-A collection of common tasks with packages using the GraphQL API.
+A collection of common tasks with package registries using the GraphQL API.
You can test out the Buildkite GraphQL API using the [Buildkite explorer](https://graphql.buildkite.com/explorer). This includes built-in documentation under the **Docs** panel.
diff --git a/pages/apis/graphql/graphql_cookbook.md b/pages/apis/graphql/graphql_cookbook.md
index d154dd8710..43d31bae8d 100644
--- a/pages/apis/graphql/graphql_cookbook.md
+++ b/pages/apis/graphql/graphql_cookbook.md
@@ -12,9 +12,9 @@ There are recipes for a range of different topics, including:
- [Builds](/docs/apis/graphql/cookbooks/builds)
- [Clusters](/docs/apis/graphql/cookbooks/clusters)
- [Jobs](/docs/apis/graphql/cookbooks/jobs)
-- [Packages](/docs/apis/graphql/cookbooks/packages)
- [Pipelines](/docs/apis/graphql/cookbooks/pipelines)
- [Pipeline templates](/docs/apis/graphql/cookbooks/pipeline-templates)
+- [Registries](/docs/apis/graphql/cookbooks/registries)
- [Rules](/docs/apis/graphql/cookbooks/rules)
- [Organizations](/docs/apis/graphql/cookbooks/organizations)
- [Teams](/docs/apis/graphql/cookbooks/teams)
diff --git a/pages/apis/rest_api/agents.md b/pages/apis/rest_api/agents.md
index e1508d9dba..878e31baa3 100644
--- a/pages/apis/rest_api/agents.md
+++ b/pages/apis/rest_api/agents.md
@@ -141,8 +141,8 @@ Success response: `200 OK`
> π Required permissions
> To stop an agent you need either
-- An Admin user API token with `write_agents` scope
-- Or, if you're using the Buildkite organization's
security for pipelines feature, a user token with the
Stop Agents permission.
+- An Admin user API token with `write_agents` [scope](/docs/apis/managing-api-tokens#token-scopes)
+- Or, if you're using the Buildkite organization's [security for pipelines](/docs/pipelines/security/permissions#manage-organization-security-for-pipelines) feature, a user token with the
Stop Agents permission.
Instruct an agent to stop accepting new build jobs and shut itself down.
diff --git a/pages/apis/rest_api/packages/packages.md b/pages/apis/rest_api/package_registries/packages.md
similarity index 86%
rename from pages/apis/rest_api/packages/packages.md
rename to pages/apis/rest_api/package_registries/packages.md
index 08085068de..9ae4c9554b 100644
--- a/pages/apis/rest_api/packages/packages.md
+++ b/pages/apis/rest_api/package_registries/packages.md
@@ -4,7 +4,7 @@ The packages API endpoint lets you create and manage packages in a registry.
## Publish a package
-The following type of `curl` syntax for publishing to registries will work across [all package ecosystems supported by Buildkite Packages](/docs/packages/ecosystems), with the `file` form-field modified accordingly.
+The following type of `curl` syntax for publishing to registries will work across [all package ecosystems supported by Buildkite Package Registries](/docs/package-registries/ecosystems), with the `file` form-field modified accordingly.
```bash
curl -H "Authorization: Bearer $TOKEN" \
@@ -14,21 +14,21 @@ curl -H "Authorization: Bearer $TOKEN" \
However, this type of REST API call is just recommended for:
-- [Alpine (apk)](/docs/packages/alpine#publish-a-package) packages
-- [Debian/Ubuntu (deb)](/docs/packages/debian#publish-a-package) packages
-- [Files (generic)](/docs/packages/files#publish-a-file)
-- [Helm (Standard)](/docs/packages/helm#publish-a-chart) charts
-- [Python (PyPI)](/docs/packages/python#publish-a-package) packages
-- [Red Hat (RPM)](/docs/packages/red-hat#publish-a-package) packages
-- [Terraform](/docs/packages/terraform#publish-a-module) modules
-
-For other supported package ecosystems, it is recommended that you use their native tools to publish to registries in your Buildkite Packages organization. These ecosystems' native tools are for:
-
-- [Container (Docker)](/docs/packages/container#publish-an-image) images
-- [Helm (OCI)](/docs/packages/helm-oci#publish-a-chart) charts
-- Java ([Maven](/docs/packages/maven#publish-a-package) or [Gradle leveraging the Maven Publish Plugin](/docs/packages/gradle#publish-a-package)) packages
-- [JavaScript (npm)](/docs/packages/javascript#publish-a-package) packages
-- [Ruby (RubyGems)](/docs/packages/ruby#publish-a-package) packages
+- [Alpine (apk)](/docs/package-registries/alpine#publish-a-package) packages
+- [Debian/Ubuntu (deb)](/docs/package-registries/debian#publish-a-package) packages
+- [Files (generic)](/docs/package-registries/files#publish-a-file)
+- [Helm (Standard)](/docs/package-registries/helm#publish-a-chart) charts
+- [Python (PyPI)](/docs/package-registries/python#publish-a-package) packages
+- [Red Hat (RPM)](/docs/package-registries/red-hat#publish-a-package) packages
+- [Terraform](/docs/package-registries/terraform#publish-a-module) modules
+
+For other supported package ecosystems, it is recommended that you use their native tools to publish to registries in your Buildkite Package Registries organization. These ecosystems' native tools are for:
+
+- [Container (Docker)](/docs/package-registries/container#publish-an-image) images
+- [Helm (OCI)](/docs/package-registries/helm-oci#publish-a-chart) charts
+- Java ([Maven](/docs/package-registries/maven#publish-a-package) or [Gradle leveraging the Maven Publish Plugin](/docs/package-registries/gradle#publish-a-package)) packages
+- [JavaScript (npm)](/docs/package-registries/javascript#publish-a-package) packages
+- [Ruby (RubyGems)](/docs/package-registries/ruby#publish-a-package) packages
The following type of response is returned by Buildkite upon a successful `curl` publishing event.
diff --git a/pages/apis/rest_api/packages/registries.md b/pages/apis/rest_api/package_registries/registries.md
similarity index 96%
rename from pages/apis/rest_api/packages/registries.md
rename to pages/apis/rest_api/package_registries/registries.md
index 555d7843ef..3e85d263ae 100644
--- a/pages/apis/rest_api/packages/registries.md
+++ b/pages/apis/rest_api/package_registries/registries.md
@@ -1,6 +1,6 @@
# Registries API
-The registries API endpoint lets you [create and manage registries](/docs/packages/manage-registries) in your organization.
+The registries API endpoint lets you [create and manage registries](/docs/package-registries/manage-registries) in your organization.
## Create a registry
@@ -48,7 +48,7 @@ Required [request body properties](/docs/api#request-body-properties):
name | Name of the new registry. Example: "my registry" . |
- ecosystem | Registry ecosystem based on the package ecosystem for the new registry. Example: "ruby" . |
+ ecosystem | Registry ecosystem based on the package ecosystem for the new registry. Example: "ruby" . |
diff --git a/pages/apis/rest_api/packages/registry_tokens.md b/pages/apis/rest_api/package_registries/registry_tokens.md
similarity index 100%
rename from pages/apis/rest_api/packages/registry_tokens.md
rename to pages/apis/rest_api/package_registries/registry_tokens.md
diff --git a/pages/apis/rest_api/analytics/_flaky_tests_query_strings.md b/pages/apis/rest_api/test_engine/_flaky_tests_query_strings.md
similarity index 81%
rename from pages/apis/rest_api/analytics/_flaky_tests_query_strings.md
rename to pages/apis/rest_api/test_engine/_flaky_tests_query_strings.md
index 459a7e50e5..5b0f11972a 100644
--- a/pages/apis/rest_api/analytics/_flaky_tests_query_strings.md
+++ b/pages/apis/rest_api/test_engine/_flaky_tests_query_strings.md
@@ -5,7 +5,7 @@
search
- Returns flaky tests with a name or scope that contains the search string. Users with the Ruby test collector installed can also filter results by location .
+ Returns flaky tests with a name or scope that contains the search string. Users with the Ruby test collector installed can also filter results by location .
Example: ?search="User#find_email" , ?search="/billing_spec"
|
diff --git a/pages/apis/rest_api/analytics/_runs_list_query_strings.md b/pages/apis/rest_api/test_engine/_runs_list_query_strings.md
similarity index 100%
rename from pages/apis/rest_api/analytics/_runs_list_query_strings.md
rename to pages/apis/rest_api/test_engine/_runs_list_query_strings.md
diff --git a/pages/apis/rest_api/analytics/flaky_tests.md b/pages/apis/rest_api/test_engine/flaky_tests.md
similarity index 92%
rename from pages/apis/rest_api/analytics/flaky_tests.md
rename to pages/apis/rest_api/test_engine/flaky_tests.md
index f5de36c0b7..d621af1cbe 100644
--- a/pages/apis/rest_api/analytics/flaky_tests.md
+++ b/pages/apis/rest_api/test_engine/flaky_tests.md
@@ -30,7 +30,7 @@ curl -H "Authorization: Bearer $TOKEN" \
Optional [query string parameters](/docs/api#query-string-parameters):
-<%= render_markdown partial: 'apis/rest_api/analytics/flaky_tests_query_strings' %>
+<%= render_markdown partial: 'apis/rest_api/test_engine/flaky_tests_query_strings' %>
Required scope: `read_suites`
diff --git a/pages/apis/rest_api/analytics/runs.md b/pages/apis/rest_api/test_engine/runs.md
similarity index 96%
rename from pages/apis/rest_api/analytics/runs.md
rename to pages/apis/rest_api/test_engine/runs.md
index f8c52d183b..bfe279c109 100644
--- a/pages/apis/rest_api/analytics/runs.md
+++ b/pages/apis/rest_api/test_engine/runs.md
@@ -26,7 +26,7 @@ curl -H "Authorization: Bearer $TOKEN" \
Optional [query string parameters](/docs/api#query-string-parameters):
-<%= render_markdown partial: 'apis/rest_api/analytics/runs_list_query_strings' %>
+<%= render_markdown partial: 'apis/rest_api/test_engine/runs_list_query_strings' %>
Required scope: `read_suites`
diff --git a/pages/apis/rest_api/analytics/suites.md b/pages/apis/rest_api/test_engine/suites.md
similarity index 100%
rename from pages/apis/rest_api/analytics/suites.md
rename to pages/apis/rest_api/test_engine/suites.md
diff --git a/pages/apis/rest_api/analytics/tests.md b/pages/apis/rest_api/test_engine/tests.md
similarity index 100%
rename from pages/apis/rest_api/analytics/tests.md
rename to pages/apis/rest_api/test_engine/tests.md
diff --git a/pages/integrations.md b/pages/integrations.md
index 102346ae5b..82a810f7d5 100644
--- a/pages/integrations.md
+++ b/pages/integrations.md
@@ -6,4 +6,4 @@ template: "landing_page"
<%= tiles "integrations" %>
-If you're looking for [Source control integrations](/docs/integrations/source-control) for Pipelines, they are over in the [Pipelines](/docs/integrations/source-control) nav.
+Learn more about source control integrations in [Connect source control](/docs/integrations/source-control).
diff --git a/pages/package_registries.md b/pages/package_registries.md
new file mode 100644
index 0000000000..76288c97c1
--- /dev/null
+++ b/pages/package_registries.md
@@ -0,0 +1,52 @@
+---
+template: "landing_page"
+---
+
+# Buildkite Package Registries
+
+Scale out asset management for faster builds and deployments across any ecosystem with _Buildkite Package Registries_. Secure your supply chain and avoid the bottlenecks of poorly managed and insecure dependencies.
+
+Package Registries allows you to:
+
+- Manage artifacts and packages from [Buildkite Pipelines](/docs/pipelines), as well as other CI/CD applications that require artifact management.
+
+- Provide registries to store your [packages and other package-like file formats](/docs/package-registries/background) such as container images and Terraform modules.
+
+As well as storing a collection of packages, a registry also surfaces metadata or attributes associated with a package, such as the package's description, version, contents (files and directories), checksum details, distribution type, dependencies, and so on.
+
+> π
+> Customers on legacy Buildkite plans can enable [Package Registries](https://buildkite.com/platform/package-registries) through the [**Organization Settings** page](/docs/package-registries/security/permissions#enabling-buildkite-packages).
+
+_Buildkite Package Registries_ was previously called _Buildkite Packages_.
+
+## Get started
+
+Run through the [Getting started](/docs/package-registries/getting-started) tutorial for a step-by-step guide on how to use Buildkite Package Registries.
+
+If you're familiar with the basics, explore how to use registries for each of Buildkite Package Registries' supported package ecosystems:
+
+
+
+
+ <%= button ":alpine: Alpine (apk)", "/docs/package-registries/alpine" %>
+ <%= button ":docker: Container (Docker)", "/docs/package-registries/container" %>
+ <%= button ":debian: Debian/Ubuntu (deb)", "/docs/package-registries/debian" %>
+ <%= button ":package: Files (generic)", "/docs/package-registries/files" %>
+ <%= button ":helm: Helm (OCI)", "/docs/package-registries/helm-oci" %>
+ <%= button ":helm: Helm", "/docs/package-registries/helm" %>
+ <%= button ":maven: Java (Maven)", "/docs/package-registries/maven" %>
+ <%= button ":gradle: Java (Gradle)", "/docs/package-registries/gradle" %>
+ <%= button ":node: JavaScript (npm)", "/docs/package-registries/javascript" %>
+ <%= button ":python: Python (PyPI)", "/docs/package-registries/python" %>
+ <%= button ":redhat: Red Hat (RPM)", "/docs/package-registries/red-hat" %>
+ <%= button ":ruby: Ruby (RubyGems)", "/docs/package-registries/ruby" %>
+ <%= button ":terraform: Terraform (modules)", "/docs/package-registries/terraform" %>
+
+
+
+
+Learn more about how to:
+
+- Work with registries in [Manage registries](/docs/package-registries/manage-registries).
+- Manage access to your registries in [User, team, and registry permissions](/docs/package-registries/security/permissions).
+- Configure your own private storage for Buildkite Package Registries in [Private storage](/docs/package-registries/private-storage).
diff --git a/pages/packages/_access_java_package_details_page.md b/pages/package_registries/_access_java_package_details_page.md
similarity index 100%
rename from pages/packages/_access_java_package_details_page.md
rename to pages/package_registries/_access_java_package_details_page.md
diff --git a/pages/packages/_alpine_registry_slug.md b/pages/package_registries/_alpine_registry_slug.md
similarity index 100%
rename from pages/packages/_alpine_registry_slug.md
rename to pages/package_registries/_alpine_registry_slug.md
diff --git a/pages/packages/_container_registry_slug.md b/pages/package_registries/_container_registry_slug.md
similarity index 100%
rename from pages/packages/_container_registry_slug.md
rename to pages/package_registries/_container_registry_slug.md
diff --git a/pages/packages/_debian_registry_slug.md b/pages/package_registries/_debian_registry_slug.md
similarity index 100%
rename from pages/packages/_debian_registry_slug.md
rename to pages/package_registries/_debian_registry_slug.md
diff --git a/pages/packages/_file_details_page_sections.md b/pages/package_registries/_file_details_page_sections.md
similarity index 100%
rename from pages/packages/_file_details_page_sections.md
rename to pages/package_registries/_file_details_page_sections.md
diff --git a/pages/packages/_helm_registry_slug.md b/pages/package_registries/_helm_registry_slug.md
similarity index 100%
rename from pages/packages/_helm_registry_slug.md
rename to pages/package_registries/_helm_registry_slug.md
diff --git a/pages/packages/_java_package_domain_name_version.md b/pages/package_registries/_java_package_domain_name_version.md
similarity index 100%
rename from pages/packages/_java_package_domain_name_version.md
rename to pages/package_registries/_java_package_domain_name_version.md
diff --git a/pages/packages/_java_registry_id.md b/pages/package_registries/_java_registry_id.md
similarity index 100%
rename from pages/packages/_java_registry_id.md
rename to pages/package_registries/_java_registry_id.md
diff --git a/pages/packages/_java_registry_slug.md b/pages/package_registries/_java_registry_slug.md
similarity index 100%
rename from pages/packages/_java_registry_slug.md
rename to pages/package_registries/_java_registry_slug.md
diff --git a/pages/packages/_javascript_registry_slug.md b/pages/package_registries/_javascript_registry_slug.md
similarity index 100%
rename from pages/packages/_javascript_registry_slug.md
rename to pages/package_registries/_javascript_registry_slug.md
diff --git a/pages/packages/_javascript_registry_write_token.md b/pages/package_registries/_javascript_registry_write_token.md
similarity index 100%
rename from pages/packages/_javascript_registry_write_token.md
rename to pages/package_registries/_javascript_registry_write_token.md
diff --git a/pages/packages/_org_slug.md b/pages/package_registries/_org_slug.md
similarity index 100%
rename from pages/packages/_org_slug.md
rename to pages/package_registries/_org_slug.md
diff --git a/pages/packages/_package_details_page_sections.md b/pages/package_registries/_package_details_page_sections.md
similarity index 100%
rename from pages/packages/_package_details_page_sections.md
rename to pages/package_registries/_package_details_page_sections.md
diff --git a/pages/packages/_path_to_file.md b/pages/package_registries/_path_to_file.md
similarity index 100%
rename from pages/packages/_path_to_file.md
rename to pages/package_registries/_path_to_file.md
diff --git a/pages/packages/_python_registry_slug.md b/pages/package_registries/_python_registry_slug.md
similarity index 100%
rename from pages/packages/_python_registry_slug.md
rename to pages/package_registries/_python_registry_slug.md
diff --git a/pages/packages/_red_hat_registry_slug.md b/pages/package_registries/_red_hat_registry_slug.md
similarity index 100%
rename from pages/packages/_red_hat_registry_slug.md
rename to pages/package_registries/_red_hat_registry_slug.md
diff --git a/pages/packages/_registry_slug.md b/pages/package_registries/_registry_slug.md
similarity index 100%
rename from pages/packages/_registry_slug.md
rename to pages/package_registries/_registry_slug.md
diff --git a/pages/packages/_ruby_registry_slug.md b/pages/package_registries/_ruby_registry_slug.md
similarity index 100%
rename from pages/packages/_ruby_registry_slug.md
rename to pages/package_registries/_ruby_registry_slug.md
diff --git a/pages/packages/_ruby_registry_write_token.md b/pages/package_registries/_ruby_registry_write_token.md
similarity index 100%
rename from pages/packages/_ruby_registry_write_token.md
rename to pages/package_registries/_ruby_registry_write_token.md
diff --git a/pages/packages/_supported_package_ecosystems.md b/pages/package_registries/_supported_package_ecosystems.md
similarity index 100%
rename from pages/packages/_supported_package_ecosystems.md
rename to pages/package_registries/_supported_package_ecosystems.md
diff --git a/pages/packages/_terraform_registry_slug.md b/pages/package_registries/_terraform_registry_slug.md
similarity index 100%
rename from pages/packages/_terraform_registry_slug.md
rename to pages/package_registries/_terraform_registry_slug.md
diff --git a/pages/packages/alpine.md b/pages/package_registries/alpine.md
similarity index 83%
rename from pages/packages/alpine.md
rename to pages/package_registries/alpine.md
index a87e1d9554..45d7cb9b21 100644
--- a/pages/packages/alpine.md
+++ b/pages/package_registries/alpine.md
@@ -1,8 +1,8 @@
# Alpine
-Buildkite Packages provides registry support for Alpine-based (apk) packages for Alpine Linux operating systems.
+Buildkite Package Registries provides registry support for Alpine-based (apk) packages for Alpine Linux operating systems.
-Once your Alpine registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the relevant `curl` command presented on your Alpine registry's details page.
+Once your Alpine registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the relevant `curl` command presented on your Alpine registry's details page.
To view and copy this `curl` command:
@@ -28,13 +28,13 @@ curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/alpine_registry_slug' %>
+<%= render_markdown partial: 'package_registries/alpine_registry_slug' %>
- `$REGISTRY_WRITE_TOKEN` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your Alpine registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
-<%= render_markdown partial: 'packages/path_to_file' %>
+<%= render_markdown partial: 'package_registries/path_to_file' %>
For example, to upload the file `my-alpine-package_0.1.1_r0.apk` from the current directory to the **My Alpine packages** registry in the **My organization** Buildkite organization, run the `curl` command:
@@ -54,7 +54,7 @@ To access your apk package's details page:
1. Select your Alpine registry on this page.
1. On your Alpine registry page, select the package to display its details page.
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
### Downloading a package
@@ -83,11 +83,11 @@ echo "https://buildkite:{registry.read.token}@packages.buildkite.com/{org.slug}/
where:
-- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Alpine registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
+- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Alpine registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/debian_registry_slug' %>
+<%= render_markdown partial: 'package_registries/debian_registry_slug' %>
**Step 2**: Install the registry signing key:
diff --git a/pages/packages/background.md b/pages/package_registries/background.md
similarity index 86%
rename from pages/packages/background.md
rename to pages/package_registries/background.md
index c6355ac5ae..b3f6646001 100644
--- a/pages/packages/background.md
+++ b/pages/package_registries/background.md
@@ -36,7 +36,7 @@ Some advanced package creation tools include:
Learn more about how:
-- Buildkite Packages works through this step-by-step [Getting started](/docs/packages/getting-started) tutorial.
-- To work with Buildkite Packages registries in [Manage registries](/docs/packages/manage-registries).
-- To manage access to your registries in [Access controls](/docs/packages/permissions).
-- To configure your own private storage for Buildkite Packages in [Private storage](/docs/packages/private-storage).
+- Buildkite Package Registries works through this step-by-step [Getting started](/docs/package-registries/getting-started) tutorial.
+- To work with registries in [Manage registries](/docs/package-registries/manage-registries).
+- To manage access to your registries in [Access controls](/docs/package-registries/security/permissions).
+- To configure your own private storage for Buildkite Package Registries in [Private storage](/docs/package-registries/private-storage).
diff --git a/pages/packages/container.md b/pages/package_registries/container.md
similarity index 83%
rename from pages/packages/container.md
rename to pages/package_registries/container.md
index 549e72d6b9..2e87df749e 100644
--- a/pages/packages/container.md
+++ b/pages/package_registries/container.md
@@ -1,8 +1,8 @@
# Container
-Buildkite Packages provides registry support for container-based (Docker) images.
+Buildkite Package Registries provides registry support for container-based (Docker) images.
-Once your container registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload images (generated from your application's build) to this registry via relevant `docker` commands presented on your container registry's details page.
+Once your container registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload images (generated from your application's build) to this registry via relevant `docker` commands presented on your container registry's details page.
To view and copy these `docker` commands:
@@ -29,8 +29,8 @@ The following steps describe the process above:
where:
* `registry-write-token` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your container registry. Ensure this access token has the **Read Packages** and **Write Packages** REST API scopes, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
- <%= render_markdown partial: 'packages/org_slug' %>
- <%= render_markdown partial: 'packages/container_registry_slug' %>
+ <%= render_markdown partial: 'package_registries/org_slug' %>
+ <%= render_markdown partial: 'package_registries/container_registry_slug' %>
1. Copy the following `docker tag` command, paste it into your terminal, and modify as required before running to tag your container image:
@@ -108,11 +108,11 @@ docker login packages.buildkite.com/{org.slug}/{registry.slug} -u buildkite -p r
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/container_registry_slug' %>
+<%= render_markdown partial: 'package_registries/container_registry_slug' %>
-- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your container registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your container registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
> π
> This step is not required for public container registries.
@@ -127,9 +127,9 @@ docker pull packages.buildkite.com/{org.slug}/{registry.slug}/image-name:tag
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/container_registry_slug' %>
+<%= render_markdown partial: 'package_registries/container_registry_slug' %>
- `image-name` is the name of your image.
diff --git a/pages/packages/debian.md b/pages/package_registries/debian.md
similarity index 77%
rename from pages/packages/debian.md
rename to pages/package_registries/debian.md
index a2b1f4f5f8..f847165bf3 100644
--- a/pages/packages/debian.md
+++ b/pages/package_registries/debian.md
@@ -1,8 +1,8 @@
# Debian
-Buildkite Packages provides registry support for Debian-based (deb) packages for Debian and Ubuntu operating system variants.
+Buildkite Package Registries provides registry support for Debian-based (deb) packages for Debian and Ubuntu operating system variants.
-Once your Debian registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the `curl` command presented on your Debian registry's details page.
+Once your Debian registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the `curl` command presented on your Debian registry's details page.
To view and copy this `curl` command:
@@ -28,13 +28,13 @@ curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/debian_registry_slug' %>
+<%= render_markdown partial: 'package_registries/debian_registry_slug' %>
- `$REGISTRY_WRITE_TOKEN` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your Debian registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
-<%= render_markdown partial: 'packages/path_to_file' %>
+<%= render_markdown partial: 'package_registries/path_to_file' %>
For example, to upload the file `my-deb-package_1.0-2_amd64.deb` from the current directory to the **My Debian packages** registry in the **My organization** Buildkite organization, run the `curl` command:
@@ -54,7 +54,7 @@ To access your deb package's details page:
1. Select your Debian registry on this page.
1. On your Debian registry page, select the package to display its details page.
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
### Downloading a package
@@ -89,11 +89,11 @@ curl -fsSL "https://buildkite:{registry.read.token}@packages.buildkite.com/{org.
where:
-- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Debian registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
+- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Debian registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/debian_registry_slug' %>
+<%= render_markdown partial: 'package_registries/debian_registry_slug' %>
If your registry is _private_ (that is, the default registry configuration), stash the private registry credentials into `apt`'s `auth.conf.d` directory:
diff --git a/pages/package_registries/ecosystems.md b/pages/package_registries/ecosystems.md
new file mode 100644
index 0000000000..32d2df0f4d
--- /dev/null
+++ b/pages/package_registries/ecosystems.md
@@ -0,0 +1,9 @@
+---
+toc: false
+---
+
+# Package ecosystems overview
+
+Buildkite Package Registries supports the following language and package ecosystems:
+
+<%= render_markdown partial: 'package_registries/supported_package_ecosystems' %>
diff --git a/pages/packages/files.md b/pages/package_registries/files.md
similarity index 79%
rename from pages/packages/files.md
rename to pages/package_registries/files.md
index 5ba0aa15e0..3769a83f47 100644
--- a/pages/packages/files.md
+++ b/pages/package_registries/files.md
@@ -1,9 +1,9 @@
# Files
-Buildkite Packages provides registry support for generic files to cover some cases where native package management isn't required.
+Buildkite Package Registries provides registry support for generic files to cover some cases where native package management isn't required.
-Once your Files registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload files (of any type and extension) to this registry via the relevant `curl` command presented on your registry details page.
+Once your Files registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload files (of any type and extension) to this registry via the relevant `curl` command presented on your registry details page.
To view and copy this `curl` command:
@@ -29,13 +29,13 @@ curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/registry_slug' %>
+<%= render_markdown partial: 'package_registries/registry_slug' %>
- `$REGISTRY_WRITE_TOKEN` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload files to your registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish files to any registry your user account has access to within your Buildkite organization.
-<%= render_markdown partial: 'packages/path_to_file' %>
+<%= render_markdown partial: 'package_registries/path_to_file' %>
For example, to upload the file `my-custom-app.ipa` from the current directory to the **My files** registry in the **My organization** Buildkite organization, run the `curl` command:
@@ -55,7 +55,7 @@ To access your file details page:
1. Select your registry on this page.
1. On your registry page, select the file to display its details page.
-<%= render_markdown partial: 'packages/file_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/file_details_page_sections' %>
### Downloading a file
diff --git a/pages/packages/getting_started.md b/pages/package_registries/getting_started.md
similarity index 84%
rename from pages/packages/getting_started.md
rename to pages/package_registries/getting_started.md
index 57ae2fd495..783d7e0416 100644
--- a/pages/packages/getting_started.md
+++ b/pages/package_registries/getting_started.md
@@ -1,8 +1,8 @@
# Getting started
-π Welcome to Buildkite Packages! You can use Packages to house your [packages](/docs/packages/background#package-creation-tools) built through [Buildkite Pipelines](/docs/pipelines) or another CI/CD application, and manage them through dedicated registries. This tutorial takes you through creating a JavaScript registry, cloning and running a simple Node.js package locally, and uploading this package to your new JavaScript registry.
+π Welcome to Buildkite Package Registries! You can use Package Registries to house your [packages](/docs/package-registries/background#package-creation-tools) built through [Buildkite Pipelines](/docs/pipelines) or another CI/CD application, and manage them through dedicated registries. This tutorial takes you through creating a JavaScript registry, cloning and running a simple Node.js package locally, and uploading this package to your new JavaScript registry.
-While this tutorial uses a Node.js package example, Buildkite Packages supports [other package ecosystems](/docs/packages/manage-registries#create-a-registry-manage-packages-in-a-registry) too.
+While this tutorial uses a Node.js package example, Buildkite Package Registries supports [other package ecosystems](/docs/package-registries/manage-registries#create-a-registry-manage-packages-in-a-registry) too.
## Before you start
@@ -23,7 +23,7 @@ First, create a new JavaScript registry:
1. On the **New Registry** page, enter the mandatory **Name** for your registry. For example, `My JavaScript registry`.
1. Enter an optional **Description** for the registry, which will appear under the name of the registry item on the **Registries** page. For example, `This is an example of a JavaScript registry`.
1. Select the required registry **Ecosystem** of **JavaScript (npm)**.
-1. If your Buildkite organization has the [teams feature](/docs/packages/permissions) enabled, select the relevant **Teams** to be granted access to the new JavaScript registry.
+1. If your Buildkite organization has the [teams feature](/docs/package-registries/security/permissions) enabled, select the relevant **Teams** to be granted access to the new JavaScript registry.
1. Select **Create Registry**.
The new JavaScript registry's details page is displayed. Selecting **Packages** in the global navigation opens the **Registries** page, where your new registry will be listed.
@@ -60,9 +60,9 @@ Next, configure your Node.js environment to publish Node.js packages to [the Jav
```
where:
- <%= render_markdown partial: 'packages/org_slug' %>
- <%= render_markdown partial: 'packages/javascript_registry_slug' %>
- <%= render_markdown partial: 'packages/javascript_registry_write_token' %>
+ <%= render_markdown partial: 'package_registries/org_slug' %>
+ <%= render_markdown partial: 'package_registries/javascript_registry_slug' %>
+ <%= render_markdown partial: 'package_registries/javascript_registry_write_token' %>
**Note:**
* If your `.npmrc` file doesn't exist, this command will automatically create it for you.
@@ -74,7 +74,7 @@ Next, configure your Node.js environment to publish Node.js packages to [the Jav
{
"name": "nodejs-example-package",
"version": "1.0.1",
- "description": "An example Node.js package for Buildkite Packages",
+ "description": "An example Node.js package for Buildkite Package Registries",
"main": "index.js",
"scripts": {
"main": "node index.js"
@@ -131,4 +131,4 @@ Your JavaScript registry's details page should show your new package with the in
That's it! You've created a new Buildkite registry, configured your Node.js environment and project to publish to your new JavaScript registry, and published a Node.js package to this registry. π
-Learn more about how to work with Buildkite Packages in [Manage registries](/docs/packages/manage-registries).
+Learn more about how to work with Buildkite Package Registries in [Manage registries](/docs/package-registries/manage-registries).
diff --git a/pages/packages/gradle.md b/pages/package_registries/gradle.md
similarity index 74%
rename from pages/packages/gradle.md
rename to pages/package_registries/gradle.md
index d4ca27beba..cba05186c1 100644
--- a/pages/packages/gradle.md
+++ b/pages/package_registries/gradle.md
@@ -1,8 +1,8 @@
# Gradle
-Buildkite Packages provides registry support for Gradle-based Java packages (using the [Maven Publish Plugin](https://docs.gradle.org/current/userguide/publishing_maven.html)).
+Buildkite Package Registries provides registry support for Gradle-based Java packages (using the [Maven Publish Plugin](https://docs.gradle.org/current/userguide/publishing_maven.html)).
-Once your Java registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry by configuring your `build.gradle` file with the Gradle snippet presented on your Java registry's details page.
+Once your Java registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry by configuring your `build.gradle` file with the Gradle snippet presented on your Java registry's details page.
To view and copy the required `build.gradle` configurations:
@@ -69,11 +69,11 @@ The following steps describe the process above:
where:
* `registry-write-token` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your Java registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
- <%= render_markdown partial: 'packages/java_package_domain_name_version' %>
+ <%= render_markdown partial: 'package_registries/java_package_domain_name_version' %>
- <%= render_markdown partial: 'packages/org_slug' %>
+ <%= render_markdown partial: 'package_registries/org_slug' %>
- <%= render_markdown partial: 'packages/java_registry_slug' %>
+ <%= render_markdown partial: 'package_registries/java_registry_slug' %>
1. Publish your package:
@@ -83,9 +83,9 @@ The following steps describe the process above:
## Access a package's details
-<%= render_markdown partial: 'packages/access_java_package_details_page' %>
+<%= render_markdown partial: 'package_registries/access_java_package_details_page' %>
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
### Downloading a package
@@ -127,10 +127,10 @@ where:
- `{org.slug}` is the org slug.
-<%= render_markdown partial: 'packages/java_registry_slug' %>
+<%= render_markdown partial: 'package_registries/java_registry_slug' %>
-- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Java registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Java registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
**Note:** Both the `authentication` and `credentials` sections are not required for registries that are publicly accessible.
-<%= render_markdown partial: 'packages/java_package_domain_name_version' %>
+<%= render_markdown partial: 'package_registries/java_package_domain_name_version' %>
diff --git a/pages/packages/helm.md b/pages/package_registries/helm.md
similarity index 78%
rename from pages/packages/helm.md
rename to pages/package_registries/helm.md
index 1a574e2cff..8d78b46e8f 100644
--- a/pages/packages/helm.md
+++ b/pages/package_registries/helm.md
@@ -1,10 +1,10 @@
# Helm
-Buildkite Packages provides Helm registry support for distributing Helm charts.
+Buildkite Package Registries provides Helm registry support for distributing Helm charts.
-This page is for standard Helm publishing instructions, alternatively you can also publish to an [OCI-based registry](/docs/packages/helm-oci).
+This page is for standard Helm publishing instructions, alternatively you can also publish to an [OCI-based registry](/docs/package-registries/helm-oci).
-Once your Helm registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload charts (generated from `helm package` to create the package) to this registry via the relevant `curl` command presented on your Helm registry's details page.
+Once your Helm registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload charts (generated from `helm package` to create the package) to this registry via the relevant `curl` command presented on your Helm registry's details page.
To view and copy this `curl` command:
@@ -30,11 +30,11 @@ curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/helm_registry_slug' %>
+<%= render_markdown partial: 'package_registries/helm_registry_slug' %>
-<%= render_markdown partial: 'packages/path_to_file' %>
+<%= render_markdown partial: 'package_registries/path_to_file' %>
For example, to upload the file `my-helm-chart-0.1.2.tgz` from the current directory to the **My Helm Charts** registry in the **My organization** Buildkite organization, run the `curl` command:
@@ -87,11 +87,11 @@ helm repo add {registry.slug} https://packages.buildkite.com/{org.slug}/{registr
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/helm_registry_slug' %>
+<%= render_markdown partial: 'package_registries/helm_registry_slug' %>
-- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download charts from your Helm registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download charts from your Helm registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
> π
> This step is not required for public Helm registries.
@@ -107,7 +107,7 @@ helm install "chart-release" "{registry.slug}/{chart-name}" --version {version}
where:
-<%= render_markdown partial: 'packages/helm_registry_slug' %>
+<%= render_markdown partial: 'package_registries/helm_registry_slug' %>
- `chart-release` is the unique release name for the Helm chart - must have no `.` in name and be in lowercase. [General conventions](https://helm.sh/docs/chart_best_practices/conventions/#chart-names).
diff --git a/pages/packages/helm_oci.md b/pages/package_registries/helm_oci.md
similarity index 78%
rename from pages/packages/helm_oci.md
rename to pages/package_registries/helm_oci.md
index 383ad253cc..471e1d2f40 100644
--- a/pages/packages/helm_oci.md
+++ b/pages/package_registries/helm_oci.md
@@ -1,8 +1,8 @@
# Helm OCI
-Buildkite Packages provides Helm OCI based registry support for distributing Helm charts. Note, this requires [Helm version 3.8.0](https://helm.sh/docs/topics/registries/) or newer.
+Buildkite Package Registries provides Helm OCI based registry support for distributing Helm charts. Note, this requires [Helm version 3.8.0](https://helm.sh/docs/topics/registries/) or newer.
-Once your Helm OCI registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload charts (generated from your application's build) to this registry via relevant `helm` commands presented on your registry's details page.
+Once your Helm OCI registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload charts (generated from your application's build) to this registry via relevant `helm` commands presented on your registry's details page.
To view and copy these `helm` commands:
@@ -28,8 +28,8 @@ The following steps describe the process above:
where:
* `registry-write-token` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload charts to your Helm registry. Ensure this access token has the **Read Packages** and **Write Packages** REST API scopes, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
- <%= render_markdown partial: 'packages/org_slug' %>
- <%= render_markdown partial: 'packages/helm_registry_slug' %>
+ <%= render_markdown partial: 'package_registries/org_slug' %>
+ <%= render_markdown partial: 'package_registries/helm_registry_slug' %>
1. Copy the following `helm push` command, paste it into your terminal, and modify as required before running to push your Helm chart:
@@ -90,11 +90,11 @@ helm registry login packages.buildkite.com/{org.slug}/{registry.slug} -u buildki
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/helm_registry_slug' %>
+<%= render_markdown partial: 'package_registries/helm_registry_slug' %>
-- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download charts from your Helm registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download charts from your Helm registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
> π
> This step is not required for public Helm registries.
@@ -109,9 +109,9 @@ helm pull oci://packages.buildkite.com/{org.slug}/{registry.slug}/chart-name --v
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/helm_registry_slug' %>
+<%= render_markdown partial: 'package_registries/helm_registry_slug' %>
- `chart-name` is the name of your chart.
diff --git a/pages/packages/javascript.md b/pages/package_registries/javascript.md
similarity index 76%
rename from pages/packages/javascript.md
rename to pages/package_registries/javascript.md
index 23e017e384..38652aa3f1 100644
--- a/pages/packages/javascript.md
+++ b/pages/package_registries/javascript.md
@@ -1,8 +1,8 @@
# JavaScript
-Buildkite Packages provides registry support for JavaScript-based (Node.js npm) packages.
+Buildkite Package Registries provides registry support for JavaScript-based (Node.js npm) packages.
-Once your JavaScript registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry by configuring your `~/.npmrc` and application's relevant `package.json` files with the command/code snippets presented on your JavaScript registry's details page.
+Once your JavaScript registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry by configuring your `~/.npmrc` and application's relevant `package.json` files with the command/code snippets presented on your JavaScript registry's details page.
To view and copy the required command/code snippet for your `~/.npmrc` and `package.json` configurations:
@@ -26,9 +26,9 @@ The following steps describe the process above:
```
where:
- <%= render_markdown partial: 'packages/org_slug' %>
- <%= render_markdown partial: 'packages/javascript_registry_slug' %>
- <%= render_markdown partial: 'packages/javascript_registry_write_token' %>
+ <%= render_markdown partial: 'package_registries/org_slug' %>
+ <%= render_markdown partial: 'package_registries/javascript_registry_slug' %>
+ <%= render_markdown partial: 'package_registries/javascript_registry_write_token' %>
**Note:**
* If your `.npmrc` file doesn't exist, this command automatically creates it for you.
@@ -62,7 +62,7 @@ To access your JavaScript package's details page:
1. Select your JavaScript registry on this page.
1. On your JavaScript registry page, select the package to display its details page.
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
### Downloading a package
@@ -90,11 +90,11 @@ npm set //packages.buildkite.com/{org.slug}/{registry.slug}/npm/:_authToken regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/javascript_registry_slug' %>
+<%= render_markdown partial: 'package_registries/javascript_registry_slug' %>
-- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages to your JavaScript registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages to your JavaScript registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
> π
> If your `.npmrc` file doesn't exist, this command automatically creates it for you.
@@ -115,6 +115,6 @@ where:
- `version.number` is the version of your Node.js package (that is, the `version` field value from its `package.json` file).
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/javascript_registry_slug' %>
+<%= render_markdown partial: 'package_registries/javascript_registry_slug' %>
diff --git a/pages/packages/manage_registries.md b/pages/package_registries/manage_registries.md
similarity index 82%
rename from pages/packages/manage_registries.md
rename to pages/package_registries/manage_registries.md
index 02f9ad8e78..bbe6b8e8c0 100644
--- a/pages/packages/manage_registries.md
+++ b/pages/package_registries/manage_registries.md
@@ -15,8 +15,8 @@ To create a new registry:
1. Select **New registry**.
1. On the **New Registry** page, enter the mandatory **Name** for your registry.
1. Enter an optional **Description** for the registry. This description appears under the name of the registry item on the **Registries** page.
-1. Select the required registry **Ecosystem** based on the [package ecosystem](/docs/packages#get-started) for this new registry.
-1. If your Buildkite organization has the [teams feature](/docs/packages/permissions) enabled, select the relevant **Teams** to be granted access to the new registry.
+1. Select the required registry **Ecosystem** based on the [package ecosystem](/docs/package-registries#get-started) for this new registry.
+1. If your Buildkite organization has the [teams feature](/docs/package-registries/security/permissions) enabled, select the relevant **Teams** to be granted access to the new registry.
1. Select **Create Registry**.
The new registry's details page is displayed. Selecting **Packages** in the global navigation opens the **Registries** page, where your new registry will be listed.
@@ -25,7 +25,7 @@ To create a new registry:
Once a [registry is created](#create-a-registry), packages can then be uploaded to it. Learn more about how to manage packages for your registry's relevant language and package ecosystem:
-<%= render_markdown partial: 'packages/supported_package_ecosystems' %>
+<%= render_markdown partial: 'package_registries/supported_package_ecosystems' %>
## Update a registry
@@ -38,9 +38,9 @@ The following aspects of a registry can be updated:
- **Emoji**: to change the emoji of the registry from the default provided when the registry was [created](#create-a-registry). The emoji appears next to the registry's name.
- **Color**: the background color for the emoji
- **Registry Management**: the privacy settings for the registryβprivate (the initial default state for all newly created registries) or public.
-- **OIDC Policy**: one or more [policies defining which OpenID Connect (OIDC) tokens](/docs/packages/security/oidc), from the [Buildkite Agent](/docs/agent/v3/cli-oidc) or another third-party system, can be used to publish/upload packages to the registry.
+- **OIDC Policy**: one or more [policies defining which OpenID Connect (OIDC) tokens](/docs/package-registries/security/oidc), from the [Buildkite Agent](/docs/agent/v3/cli-oidc) or another third-party system, can be used to publish/upload packages to the registry.
- **Tokens** (private registries only): one or more [registry tokens](#update-a-registry-configure-registry-tokens), which are an alternative to API access tokens.
-- **Storage**: choose your [registry storage](#update-a-registry-configure-registry-storage), selecting from **Buildkite-hosted storage** (the initially default storage system) or [your own private AWS S3 bucket](/docs/packages/private-storage) to store packages for this registry.
+- **Storage**: choose your [registry storage](#update-a-registry-configure-registry-storage), selecting from **Buildkite-hosted storage** (the initially default storage system) or [your own private AWS S3 bucket](/docs/package-registries/private-storage) to store packages for this registry.
The registry's ecosystem type cannot be changed once the registry is created.
@@ -60,11 +60,11 @@ To update a registry:
The registry's updates will appear on the **Registries** page, as well as the registry's details page.
-1. If the registry's _OIDC policy_ needs to be configured, learn more about this in [OIDC in Buildkite Packages](/docs/packages/security/oidc).
+1. If the registry's _OIDC policy_ needs to be configured, learn more about this in [OIDC in Buildkite Package Registries](/docs/package-registries/security/oidc).
1. If the registry is _private_ and _registry tokens_ (an alternative to API access tokens) need to be configured, learn more about this in [Configure registry tokens](#update-a-registry-configure-registry-tokens).
-1. If [_private storage_](/docs/packages/private-storage) has been configured and linked to your Buildkite organization, the storage location for the registry can be changed. Learn more about this in [Configure registry storage](#update-a-registry-configure-registry-storage).
+1. If [_private storage_](/docs/package-registries/private-storage) has been configured and linked to your Buildkite organization, the storage location for the registry can be changed. Learn more about this in [Configure registry storage](#update-a-registry-configure-registry-storage).
### Configure registry tokens
@@ -87,7 +87,7 @@ Unlike other tokens generated elsewhere in Buildkite, registry tokens can contin
### Configure registry storage
-When a new registry is [created](#create-a-registry), it automatically uses the [default Buildkite Packages storage](/docs/packages/private-storage#set-the-default-buildkite-packages-storage) location. However, your new registry's default storage location can be overridden to use another configured storage location. Learn more about configuring private storage in [Private storage links](/docs/packages/private-storage).
+When a new registry is [created](#create-a-registry), it automatically uses the [default Buildkite Package Registries storage](/docs/package-registries/private-storage#set-the-default-buildkite-package-registries-storage) location. However, your new registry's default storage location can be overridden to use another configured storage location. Learn more about configuring private storage in [Private storage links](/docs/package-registries/private-storage).
To configure/change your registry's current storage:
@@ -118,4 +118,4 @@ To delete a registry:
## Audit logging
-All events performed through Buildkite Packages are logged through the Buildkite organization's [**Audit Log** feature](/docs/pipelines/security/audit-log).
+All events performed through Buildkite Package Registries are logged through the Buildkite organization's [**Audit Log** feature](/docs/pipelines/security/audit-log).
diff --git a/pages/packages/maven.md b/pages/package_registries/maven.md
similarity index 77%
rename from pages/packages/maven.md
rename to pages/package_registries/maven.md
index 63c2617a06..a0ecefb7ad 100644
--- a/pages/packages/maven.md
+++ b/pages/package_registries/maven.md
@@ -1,8 +1,8 @@
# Maven
-Buildkite Packages provides registry support for Maven-based Java packages.
+Buildkite Package Registries provides registry support for Maven-based Java packages.
-Once your Java registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry by configuring your `~/.m2/settings.xml` and application's relevant `pom.xml` files with the Maven XML snippets presented on your Java registry's details page.
+Once your Java registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry by configuring your `~/.m2/settings.xml` and application's relevant `pom.xml` files with the Maven XML snippets presented on your Java registry's details page.
To view and copy the required `~/.m2/settings.xml` and `pom.xml` configurations:
@@ -45,7 +45,7 @@ The following steps describe the process above:
where:
* `registry-write-token` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your Java registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
- <%= render_markdown partial: 'packages/java_registry_id' %>
+ <%= render_markdown partial: 'package_registries/java_registry_id' %>
**Note:** This step only needs to be performed once for the life of your Java registry, and API access token.
@@ -67,9 +67,9 @@ The following steps describe the process above:
where:
* `org-slug-registry-slug` is the ID of your Java registry (above).
- <%= render_markdown partial: 'packages/org_slug' %>
+ <%= render_markdown partial: 'package_registries/org_slug' %>
- <%= render_markdown partial: 'packages/java_registry_slug' %>
+ <%= render_markdown partial: 'package_registries/java_registry_slug' %>
1. Publish your package:
@@ -79,9 +79,9 @@ The following steps describe the process above:
## Access a package's details
-<%= render_markdown partial: 'packages/access_java_package_details_page' %>
+<%= render_markdown partial: 'package_registries/access_java_package_details_page' %>
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
### Downloading a package
@@ -127,9 +127,9 @@ The `~/.m2/settings.xml` code snippet is based on this format:
where:
-- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Java registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
+- `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Java registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization.
-<%= render_markdown partial: 'packages/java_registry_id' %>
+<%= render_markdown partial: 'package_registries/java_registry_id' %>
The `pom.xml` code snippet is based on this format:
@@ -158,10 +158,10 @@ The `pom.xml` code snippet is based on this format:
where:
-<%= render_markdown partial: 'packages/java_registry_id' %>
+<%= render_markdown partial: 'package_registries/java_registry_id' %>
- `{org.slug}` is the org slug.
-<%= render_markdown partial: 'packages/java_registry_slug' %>
+<%= render_markdown partial: 'package_registries/java_registry_slug' %>
-<%= render_markdown partial: 'packages/java_package_domain_name_version' %>
+<%= render_markdown partial: 'package_registries/java_package_domain_name_version' %>
diff --git a/pages/packages/private_storage.md b/pages/package_registries/private_storage.md
similarity index 66%
rename from pages/packages/private_storage.md
rename to pages/package_registries/private_storage.md
index 8cfbfe5ca5..219d3b277f 100644
--- a/pages/packages/private_storage.md
+++ b/pages/package_registries/private_storage.md
@@ -1,22 +1,22 @@
# Private storage link
-This page provides details on how to link and configure your private Amazon Web Services (AWS) Simple Storage Service (S3) storage to Buildkite Packages within your Buildkite organization. These processes can only be performed by [Buildkite organization administrators](/docs/packages/permissions#manage-teams-and-permissions-organization-level-permissions).
+This page provides details on how to link and configure your private Amazon Web Services (AWS) Simple Storage Service (S3) storage to Buildkite Package Registries within your Buildkite organization. These processes can only be performed by [Buildkite organization administrators](/docs/package-registries/security/permissions#manage-teams-and-permissions-organization-level-permissions).
-By default, Buildkite Packages provides its own storage to house any packages, container images and modules stored in registries. You can also link your own private AWS S3 bucket to Buildkite Packages, which allows you to:
+By default, Buildkite Package Registries provides its own storage to house any packages, container images and modules stored in registries. You can also link your own private AWS S3 bucket to Buildkite Package Registries, which allows you to:
- Manage Buildkite registry packages, container images and modules stored within your private AWS S3 bucket (that is, your _private storage_). Private storage:
* Located closer to your geographical location may provide faster registry access.
* Mitigates network transmission costs.
-- Use Buildkite Packages' management and metadata-handling features to manage these files in registries within your private storage.
+- Use Buildkite Package Registries' management and metadata-handling features to manage these files in registries within your private storage.
-- Maintain control, ownership and sovereignty over the packages, container images and modules stored within your Buildkite Packages registries.
+- Maintain control, ownership and sovereignty over the packages, container images and modules stored within your registries managed by Buildkite Package Registries.
-Buildkite Packages uses [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) to provision its services within your private AWS S3 storage.
+Buildkite Package Registries uses [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) to provision its services within your private AWS S3 storage.
## Before you start
-Before you can start linking your private AWS S3 storage to Buildkite Packages, you will need to have created your own empty AWS S3 bucket.
+Before you can start linking your private AWS S3 storage to Buildkite Package Registries, you will need to have created your own empty AWS S3 bucket.
Learn more about:
@@ -24,15 +24,15 @@ Learn more about:
- How to create an S3 bucket from the [Amazon S3 documentation's Getting started](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html) guide.
-## Link your private storage to Buildkite Packages
+## Link your private storage to Buildkite Package Registries
-To link your private AWS S3 storage to Buildkite Packages:
+To link your private AWS S3 storage to Buildkite Package Registries:
1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page.
1. In the **Packages** section, select **Private Storage Link** to open its page.
-1. Select **Add private storage link** to begin configuring your private storage for Buildkite Packages.
+1. Select **Add private storage link** to begin configuring your private storage for Buildkite Package Registries.
1. On the **Provide your storage's details** page, in **Step 2: Create or locate your AWS S3 bucket**, select **Open AWS** to open the list of S3 buckets in your AWS account, to either retrieve your existing empty S3 bucket, or create a new one if you [haven't already done so](#before-you-start).
@@ -51,23 +51,23 @@ To link your private AWS S3 storage to Buildkite Packages:
1. Select **Create stack** to begin creating the CloudFormation stack for your S3 bucket.
-1. Once the stack is created, return to the Buildkite interface and select **Run diagnostic** to verify that Buildkite Packages can publish (`PUT`), download (`GET`) and delete (`DELETE`) packages to and from your S3 private storage.
+1. Once the stack is created, return to the Buildkite interface and select **Run diagnostic** to verify that Buildkite Package Registries can publish (`PUT`), download (`GET`) and delete (`DELETE`) packages to and from your S3 private storage.
1. Once the **Diagnostic Result** page indicates a **Pass** for each of these three tests, select **Create Private Storage Link** complete this linking process.
You are returned to the **Private Storage Link** page, where you can:
-- [Set the default Buildkite Packages storage for your Buildkite organization](#set-the-default-buildkite-packages-storage).
+- [Set the default Buildkite Package Registries storage for your Buildkite organization](#set-the-default-buildkite-package-registries-storage).
-- [Set the storage independently for each of your Buildkite registries](/docs/packages/manage-registries#update-a-registry-configure-registry-storage).
+- [Set the storage independently for each of your Buildkite registries](/docs/package-registries/manage-registries#update-a-registry-configure-registry-storage).
-## Set the default Buildkite Packages storage
+## Set the default Buildkite Package Registries storage
By default, your Buildkite organization uses storage provided by Buildkite (known as **Buildkite-hosted storage**).
-The _default storage_ is the storage used when a [new registry is created](/docs/packages/manage-registries#create-a-registry).
+The _default storage_ is the storage used when a [new registry is created](/docs/package-registries/manage-registries#create-a-registry).
-Once you have [configured at least one other private storage link](#link-your-private-storage-to-buildkite-packages), you can change the default storage to one of these configured private storage configurations. To do this:
+Once you have [configured at least one other private storage link](#link-your-private-storage-to-buildkite-package-registries), you can change the default storage to one of these configured private storage configurations. To do this:
1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page.
@@ -75,4 +75,4 @@ Once you have [configured at least one other private storage link](#link-your-pr
1. Select **Change** to switch from using **Buildkite-hosted storage** (or a previously configured private storage beginning with **s3://...**) to your new private storage link. If this setting is currently configured to use a previously configured private storage link, the default storage can also be reverted back to using **Buildkite-hosted storage**.
-All [newly created registries](/docs/packages/manage-registries#create-a-registry) will automatically use the default private storage location to house packages.
+All [newly created registries](/docs/package-registries/manage-registries#create-a-registry) will automatically use the default private storage location to house packages.
diff --git a/pages/packages/python.md b/pages/package_registries/python.md
similarity index 76%
rename from pages/packages/python.md
rename to pages/package_registries/python.md
index 020b45147f..9af9355b80 100644
--- a/pages/packages/python.md
+++ b/pages/package_registries/python.md
@@ -1,8 +1,8 @@
# Python
-Buildkite Packages provides registry support for Python-based (PyPI) packages.
+Buildkite Package Registries provides registry support for Python-based (PyPI) packages.
-Once your Python registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the `curl` command presented on your Python registry's details page.
+Once your Python registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the `curl` command presented on your Python registry's details page.
To view and copy this `curl` command:
@@ -28,13 +28,13 @@ curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/python_registry_slug' %>
+<%= render_markdown partial: 'package_registries/python_registry_slug' %>
- `$REGISTRY_WRITE_TOKEN` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your Python registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
-<%= render_markdown partial: 'packages/path_to_file' %>
+<%= render_markdown partial: 'package_registries/path_to_file' %>
For example, to upload the file `my-python-package-0.9.7b1.tar.gz` from the current directory to the **My Python packages** registry in the **My organization** Buildkite organization, run the `curl` command:
@@ -54,7 +54,7 @@ To access your Python package's details page:
1. Select your Python registry on this page.
1. On your Python registry page, select the package to display its details.
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
### Downloading a package
@@ -84,11 +84,11 @@ extra-index-url="https://buildkite:{registry.read.token}@packages.buildkite.com/
where:
-- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Python registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
+- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Python registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/python_registry_slug' %>
+<%= render_markdown partial: 'package_registries/python_registry_slug' %>
The alternative `requirements.txt` (for virtualenv) code snippet is based on this format:
diff --git a/pages/packages/red_hat.md b/pages/package_registries/red_hat.md
similarity index 75%
rename from pages/packages/red_hat.md
rename to pages/package_registries/red_hat.md
index cfb3a114f7..61c3a4724b 100644
--- a/pages/packages/red_hat.md
+++ b/pages/package_registries/red_hat.md
@@ -1,8 +1,8 @@
# Red Hat
-Buildkite Packages provides registry support for Red Hat-based (RPM) packages for Red Hat Linux operating systems.
+Buildkite Package Registries provides registry support for Red Hat-based (RPM) packages for Red Hat Linux operating systems.
-Once your Red Hat registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the relevant `curl` command presented on your Red Hat registry's details page.
+Once your Red Hat registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via the relevant `curl` command presented on your Red Hat registry's details page.
To view and copy this `curl` command:
@@ -28,13 +28,13 @@ curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/red_hat_registry_slug' %>
+<%= render_markdown partial: 'package_registries/red_hat_registry_slug' %>
- `$REGISTRY_WRITE_TOKEN` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload packages to your Red Hat registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish packages to any registry your user account has access to within your Buildkite organization.
-<%= render_markdown partial: 'packages/path_to_file' %>
+<%= render_markdown partial: 'package_registries/path_to_file' %>
For example, to upload the file `my-red-hat-package_1.0-2.x86_64.rpm` from the current directory to the **My Red Hat packages** registry in the **My organization** Buildkite organization, run the `curl` command:
@@ -54,7 +54,7 @@ To access your RPM package's details page:
1. Select your Red Hat registry on this page.
1. On your Red Hat registry page, select the package to display its details page.
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
### Downloading a package
@@ -83,13 +83,13 @@ sudo sh -c 'echo -e "[{registry.slug}]\nname={registry.name}\nbaseurl=https://bu
where:
-<%= render_markdown partial: 'packages/red_hat_registry_slug' %>
+<%= render_markdown partial: 'package_registries/red_hat_registry_slug' %>
- `{registry.name}` is the name of your Red Hat registry.
-- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Red Hat registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
+- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages from your Red Hat registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
#### Package installation
diff --git a/pages/packages/ruby.md b/pages/package_registries/ruby.md
similarity index 76%
rename from pages/packages/ruby.md
rename to pages/package_registries/ruby.md
index 34961ad725..08b0478f88 100644
--- a/pages/packages/ruby.md
+++ b/pages/package_registries/ruby.md
@@ -1,8 +1,8 @@
# Ruby
-Buildkite Packages provides registry support for Ruby-based (RubyGems) packages.
+Buildkite Package Registries provides registry support for Ruby-based (RubyGems) packages.
-Once your Ruby registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via a single command, or by configuring your `~/.gem/credentials` and `gemspec` files with the code snippets presented on your Ruby registry's details page.
+Once your Ruby registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload packages (generated from your application's build) to this registry via a single command, or by configuring your `~/.gem/credentials` and `gemspec` files with the code snippets presented on your Ruby registry's details page.
To view and copy the required command or `~/.gem/credentials` and `gemspec` configurations:
@@ -33,9 +33,9 @@ GEM_HOST_API_KEY="temporary-write-token-that-expires-after-5-minutes" \
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/ruby_registry_slug' %>
+<%= render_markdown partial: 'package_registries/ruby_registry_slug' %>
Since the `temporary-write-token-that-expires-after-5-minutes` expires quickly, it is recommended that you just copy this command directly from the **Publish a Ruby Package** dialog.
@@ -54,9 +54,9 @@ The remaining code boxes on the **Publish a Ruby Package** dialog provide config
```
where:
- <%= render_markdown partial: 'packages/org_slug' %>
- <%= render_markdown partial: 'packages/ruby_registry_slug' %>
- <%= render_markdown partial: 'packages/ruby_registry_write_token' %>
+ <%= render_markdown partial: 'package_registries/org_slug' %>
+ <%= render_markdown partial: 'package_registries/ruby_registry_slug' %>
+ <%= render_markdown partial: 'package_registries/ruby_registry_write_token' %>
**Note:** This step only needs to be conducted once for the life of your Ruby registry.
@@ -91,7 +91,7 @@ To access your Ruby package's details page:
1. Select your Ruby registry on this page.
1. On your Ruby registry page, select the package within the **Packages** section. The package's details page is displayed.
-<%= render_markdown partial: 'packages/package_details_page_sections' %>
+<%= render_markdown partial: 'package_registries/package_details_page_sections' %>
A Ruby registry's package also has a **Dependencies** tab, which lists other RubyGems gem packages that your currently viewed Ruby gem package has dependencies on.
@@ -127,8 +127,8 @@ where:
- `version.number` is the version of your RubyGems gem package
-- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download packages to your Ruby registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
+- `{registry.read.token}` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download packages to your Ruby registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download packages from any registry your user account has access to within your Buildkite organization. This URL component, along with its surrounding `buildkite:` and `@` components are not required for registries that are publicly accessible.
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
- `{registry.slug}` is the name of your Ruby registry.
diff --git a/pages/package_registries/security.md b/pages/package_registries/security.md
new file mode 100644
index 0000000000..d417be15e7
--- /dev/null
+++ b/pages/package_registries/security.md
@@ -0,0 +1,12 @@
+---
+toc: false
+---
+
+# Security
+
+Customer security is paramount to Buildkite. Buildkite Package Registries provides mechanisms to restrict access to your registries from Buildkite Agents and their pipeline's jobs, as well as other third-party systems that can issue [Open ID Connect (OIDC)](https://openid.net/developers/how-connect-works/) tokens.
+
+This section contains the following topics:
+
+- [OIDC with Buildkite Package Registries](/docs/package-registries/security/oidc) and how to restrict access to registries through OIDC policies.
+- [User, team, and registry permissions](/docs/package-registries/security/permissions) and how to manage team and user access to registries.
diff --git a/pages/packages/security/oidc.md b/pages/package_registries/security/oidc.md
similarity index 86%
rename from pages/packages/security/oidc.md
rename to pages/package_registries/security/oidc.md
index 8eba6c91d3..1e429384d6 100644
--- a/pages/packages/security/oidc.md
+++ b/pages/package_registries/security/oidc.md
@@ -1,16 +1,16 @@
-# OIDC in Buildkite Packages
+# OIDC in Buildkite Package Registries
<%= render_markdown partial: 'platform/oidc_introduction' %>
-You can configure registries in Buildkite Packages with OIDC policies that allow access using OIDC tokens issued by Buildkite Agents and other OIDC identity providers. This is similar to how [third-party products and services can be configured with OIDC policies](/docs/pipelines/security/oidc) to consume Buildkite Agent OIDC tokens for specific pipeline jobs, for deployment, or access management and security purposes.
+You can configure Buildkite registries with OIDC policies that allow access using OIDC tokens issued by Buildkite Agents and other OIDC identity providers. This is similar to how [third-party products and services can be configured with OIDC policies](/docs/pipelines/security/oidc) to consume Buildkite Agent OIDC tokens for specific pipeline jobs, for deployment, or access management and security purposes.
A Buildkite Agent's OIDC tokens assert claims about the slugs of the pipeline it is building and organization that contains this pipeline, the ID of the job that created the token, as well as other claims, such as the name of the branch used in the build, the SHA of the commit that triggered the build, and the agent ID. If the token's claims do not comply with the registry's OIDC policy, the OIDC token is rejected, and any actions attempted with that token will fail. If the claims do comply, however, the OIDC token will have read and write access to packages in the registry.
-The [Buildkite Agent's `oidc` command](/docs/agent/v3/cli-oidc) allows you to request an OIDC token from Buildkite containing claims about the pipeline's current job. These tokens can then be used by a registry in Buildkite Packages to determine (through its OIDC policy) if the organization, pipeline and any other metadata associated with the pipeline and its job are permitted to publish/upload packages to this registry.
+The [Buildkite Agent's `oidc` command](/docs/agent/v3/cli-oidc) allows you to request an OIDC token from Buildkite containing claims about the pipeline's current job. These tokens can then be used by a Buildkite registry to determine (through its OIDC policy) if the organization, pipeline and any other metadata associated with the pipeline and its job are permitted to publish/upload packages to this registry.
## OIDC token requirements
-All registries in Buildkite Packages defined with an OIDC policy, require the following claims from an OIDC token (unless indicated as optional), regardless of the OIDC identity provider that issued the token.
+All Buildkite registries defined with an OIDC policy, require the following claims from an OIDC token (unless indicated as optional), regardless of the OIDC identity provider that issued the token.
| Claim | Value |
| ----- | ----- |
@@ -43,7 +43,7 @@ Learn more about how an OIDC policy for a registry is constructed in [Policy str
### Basic OIDC policy format
-The basic format for an OIDC policy for OIDC tokens issued by a Buildkite Agent is:
+The basic format for a Buildkite registry's OIDC policy, to handle OIDC tokens issued by a Buildkite Agent is:
```yaml
- iss: https://agent.buildkite.com
@@ -64,7 +64,7 @@ However, more [complex OIDC policies](#define-an-oidc-policy-for-a-registry-comp
### Complex OIDC policy example
-The following OIDC policy for a registry in Buildkite Packages contains two [_statements_](#statements)βone for a registry in Buildkite Packages and another for GitHub Actions.
+The following OIDC policy for a Buildkite registry contains two [_statements_](#statements)βone for a registry in Package Registries and another for GitHub Actions.
```yaml
- iss: https://agent.buildkite.com
@@ -104,7 +104,7 @@ The second statement allows OIDC tokens representing a GitHub Actions workflow,
### Policy structure and behavior
-OIDC policy [_statements_](#statements) in Buildkite Packages are defined as a YAML- or JSON-formatted list, each of which includes a _token issuer_ from an OIDC identity provider, along with a map of [_claim rules_](#claim-rules).
+OIDC policy [_statements_](#statements) in Buildkite Package Registries are defined as a YAML- or JSON-formatted list, each of which includes a _token issuer_ from an OIDC identity provider, along with a map of [_claim rules_](#claim-rules).
If an OIDC token's claims match both the token issuer and _all_ claim rules defined by any statement within a registry's OIDC policy, then the token is accepted and the OIDC identity provider that issued the token is granted access to the registry. If no statements of the OIDC policy match, the token is rejected, and no registry access is granted.
@@ -128,7 +128,7 @@ Currently, only OIDC tokens from the following token issuers are supported.
| GitHub Actions | `https://token.actions.githubusercontent.com` | [GitHub Actions OIDC Tokens](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect) |
| CircleCI | `https://oidc.circleci.com/org/$ORG` where `$ORG` is your organization name | [CircleCI OIDC Tokens](https://circleci.com/docs/openid-connect-tokens) |
-If you'd like to use OIDC tokens from a different token issuer or OIDC identity provider in Buildkite Packages, please contact [support](https://buildkite.com/support).
+If you'd like to use OIDC tokens from a different token issuer or OIDC identity provider with Buildkite Package Registries, please contact [support](https://buildkite.com/support).
@@ -191,17 +191,17 @@ buildkite-agent oidc request-token --audience "https://packages.buildkite.com/{o
where:
-- `--audience` is the target system that consumes this OIDC token. For Buildkite Packages, this value must be based on the URL `https://packages.buildkite.com/{org.slug}/{registry.slug}`.
+- `--audience` is the target system that consumes this OIDC token. For Buildkite Package Registries, this value must be based on the URL `https://packages.buildkite.com/{org.slug}/{registry.slug}`.
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
- `{registry.slug}` is the slug of your registry, which is the [kebab-case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case) version of your registry name, and can be obtained after accessing **Packages** in the global navigation > your registry from the **Registries** page.
- `--lifetime` is the time (in seconds) that the OIDC token is valid for. By default, this value must be less than `300`.
-### Part 2: Authenticate the Buildkite registry with the OIDC token
+### Part 2: Authenticate the registry with the OIDC token
-To do this (using Docker as an example), authenticate the Buildkite registry with the OIDC token obtained in [part 1](#configure-a-buildkite-pipeline-to-authenticate-to-a-registry-part-1-request-an-oidc-token-from-buildkite) by piping the output through to the `docker login` command:
+To do this (using Docker as an example), authenticate the registry with the OIDC token obtained in [part 1](#configure-a-buildkite-pipeline-to-authenticate-to-a-registry-part-1-request-an-oidc-token-from-buildkite) by piping the output through to the `docker login` command:
```bash
docker login packages.buildkite.com/{org.slug}/{registry.slug} --username buildkite --password-stdin
@@ -235,7 +235,7 @@ steps:
label: "\:docker\: Build"
command: docker build --tag packages.buildkite.com/my-organization/my-pipeline/my-image:latest .
-- key: "docker-login" # Authenticate the Buildkite Agent to the Buildkite Packages registry using an OIDC token
+- key: "docker-login" # Authenticate the Buildkite Agent to the Buildkite registry using an OIDC token
label: "\:docker\: Login"
command: buildkite-agent oidc request-token --audience "https://packages.buildkite.com/my-organization/my-pipeline" --lifetime 300 | docker login packages.buildkite.com/my-organization/my-pipeline --username buildkite --password-stdin
depends_on: "docker-build"
diff --git a/pages/packages/permissions.md b/pages/package_registries/security/permissions.md
similarity index 77%
rename from pages/packages/permissions.md
rename to pages/package_registries/security/permissions.md
index 3249b85d4a..0f8b6d78a7 100644
--- a/pages/packages/permissions.md
+++ b/pages/package_registries/security/permissions.md
@@ -6,7 +6,7 @@ Enterprise customers can configure registry permissions for all users across the
## Manage teams and permissions
-To manage teams across the Buildkite Packages application, a _Buildkite organization administrator_ first needs to enable this feature across their organization. Learn more about how to do this in the [Manage teams and permissions section of Pipelines documentation](/docs/team-management/permissions#manage-teams-and-permissions).
+To manage teams across the Buildkite Package Registries application, a _Buildkite organization administrator_ first needs to enable this feature across their organization. Learn more about how to do this in the [Manage teams and permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions).
Once the _teams_ feature is enabled, you can see the teams that you're a member of from the **Users** page, which:
@@ -16,19 +16,21 @@ Once the _teams_ feature is enabled, you can see the teams that you're a member
### Organization-level permissions
-Learn more about what a _Buildkite organization administrator_ can do in the [Organization-level permissions section of the Pipelines documentation](/docs/team-management/permissions#manage-teams-and-permissions-organization-level-permissions).
+Learn more about what a _Buildkite organization administrator_ can do in the [Organization-level permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions-organization-level-permissions).
As an organization administrator, you can access the [**Organization Settings** page](https://buildkite.com/organizations/~/settings) by selecting **Settings** in the global navigation, where you can do the following:
- Add new teams or edit existing ones in the [**Team** section](https://buildkite.com/organizations/~/teams).
- * After selecting a team, you can view and administer the member-, [pipeline-](/docs/team-management/permissions#manage-teams-and-permissions-pipeline-level-permissions), [test suite-](/docs/test-analytics/permissions#manage-teams-and-permissions-test-suite-level-permissions), [registry-](#manage-teams-and-permissions-registry-level-permissions) and [team-](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions)level settings for that team.
+ * After selecting a team, you can view and administer the member-, [pipeline-](/docs/pipelines/security/permissions#manage-teams-and-permissions-pipeline-level-permissions), [test suite-](/docs/test-engine/permissions#manage-teams-and-permissions-test-suite-level-permissions), [registry-](#manage-teams-and-permissions-registry-level-permissions) and [team-](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions)level settings for that team.
-- [Enable Buildkite Packages](#enabling-buildkite-packages) for your Buildkite organization.
+- [Enable Buildkite Package Registries](#enabling-buildkite-packages) for your Buildkite organization.
-- Configure [private storage](/docs/packages/private-storage) for your Buildkite Packages registries.
+- Configure [private storage](/docs/package-registries/private-storage) for your registries in Buildkite Package Registries.
-
Enabling Buildkite Packages
+
Enabling Buildkite Package Registries
+
+Customers on legacy Buildkite plans may need to enable Package Registries to enable this product.
To do this:
@@ -39,11 +41,11 @@ To do this:
1. Select the **Enable Buildkite Packages** button, then **Enable Buildkite Packages** in the **Ready to enable Buildkite Packages** confirmation dialog.
> π
-> Once Buildkite Packages is enabled, the **Enable** link on the **Organization Settings** page changes to **Enabled** and Buildkite Packages can only be disabled by contacting [support](https://buildkite.com/support).
+> Once Buildkite Package Registries is enabled, the **Enable** link on the **Organization Settings** page changes to **Enabled** and Buildkite Package Registries can only be disabled by contacting [support](https://buildkite.com/support).
### Team-level permissions
-Learn more about what _team members_ are and what _team maintainers_ can do in the [Team-level permissions section of the Pipelines documentation](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions).
+Learn more about what _team members_ are and what _team maintainers_ can do in the [Team-level permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions).
### Registry-level permissions
@@ -86,7 +88,7 @@ These user-level permissions and security features are managed by _Buildkite org
1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page.
-1. Select [**Security** > **Packages** tab](https://buildkite.com/organizations/~/security/packages) to access your organization's security for Packages page.
+1. Select [**Security** > **Packages** tab](https://buildkite.com/organizations/~/security/packages) to access your organization's security for **Packages** page.
From this page, you can configure the following permissions for all users across your Buildkite organization:
@@ -96,4 +98,5 @@ From this page, you can configure the following permissions for all users across
## Manage an agent's access to registries
-To configure the rules by which a Buildkite Agent can access a registry, you'll need to configure the [OpenID Connect (OIDC) policy](/docs/packages/security/oidc) within the registry to allow the Buildkite Agent to request an OIDC token (using the [`buildkite-agent oidc request-token`](/docs/agent/v3/cli-oidc#request-oidc-token) command).
+To configure the rules by which a Buildkite Agent can access a registry, you'll need to configure the [OpenID Connect (OIDC) policy](/docs/packages/security/oidc) within the registry to allow the Buildkite Agent to generate an OIDC token (using the [`buildkite-agent oidc request-token`](/docs/agent/v3/cli-oidc#request-oidc-token) command), which the agent can use to authenticate to this registry.
+
diff --git a/pages/packages/terraform.md b/pages/package_registries/terraform.md
similarity index 87%
rename from pages/packages/terraform.md
rename to pages/package_registries/terraform.md
index 62142883d9..b744385dfc 100644
--- a/pages/packages/terraform.md
+++ b/pages/package_registries/terraform.md
@@ -1,8 +1,8 @@
# Terraform
-Buildkite Packages provides registry support for Terraform modules.
+Buildkite Package Registries provides registry support for Terraform modules.
-Once your Terraform registry has been [created](/docs/packages/manage-registries#create-a-registry), you can publish/upload modules (generated from your application's build) to this registry via the `curl` command presented on your Terraform registry's details page.
+Once your Terraform registry has been [created](/docs/package-registries/manage-registries#create-a-registry), you can publish/upload modules (generated from your application's build) to this registry via the `curl` command presented on your Terraform registry's details page.
To view and copy this `curl` command:
@@ -28,9 +28,9 @@ curl -X POST https://api.buildkite.com/v2/packages/organizations/{org.slug}/regi
where:
-<%= render_markdown partial: 'packages/org_slug' %>
+<%= render_markdown partial: 'package_registries/org_slug' %>
-<%= render_markdown partial: 'packages/terraform_registry_slug' %>
+<%= render_markdown partial: 'package_registries/terraform_registry_slug' %>
- `$REGISTRY_WRITE_TOKEN` is your [API access token](https://buildkite.com/user/api-access-tokens) used to publish/upload modules to your Terraform registry. Ensure this access token has the **Write Packages** REST API scope, which allows this token to publish modules and packages to any registry your user account has access to within your Buildkite organization.
@@ -100,7 +100,7 @@ To install a module:
}
```
- where `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/packages/manage-registries#update-a-registry-configure-registry-tokens) used to download modules from your Terraform registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download modules and packages from any registry your user account has access to within your Buildkite organization.
+ where `registry-read-token` is your [API access token](https://buildkite.com/user/api-access-tokens) or [registry token](/docs/package-registries/manage-registries#update-a-registry-configure-registry-tokens) used to download modules from your Terraform registry. Ensure this access token has the **Read Packages** REST API scope, which allows this token to download modules and packages from any registry your user account has access to within your Buildkite organization.
**Note:** This step only needs to be performed once for the life of your Terraform registry.
diff --git a/pages/packages.md b/pages/packages.md
deleted file mode 100644
index be5f06f9ad..0000000000
--- a/pages/packages.md
+++ /dev/null
@@ -1,48 +0,0 @@
----
-template: "landing_page"
----
-
-# Buildkite Packages
-
-Buildkite Packages is a product that:
-
-- Manages artifacts and packages from [Buildkite Pipelines](/docs/pipelines), as well as other CI/CD applications that require artifact management.
-
-- Provides registries to store your [packages and other package-like file formats](/docs/packages/background) such as container images and Terraform modules.
-
-As well as storing a collection of packages, a registry also surfaces metadata or attributes associated with a package, such as the package's description, version, contents (files and directories), checksum details, distribution type, dependencies, and so on.
-
-> π
-> You can enable [Buildkite Packages](https://buildkite.com/packages) through the [**Organization Settings** page](/docs/packages/permissions#enabling-buildkite-packages).
-
-## Get started
-
-Run through the [Getting started](/docs/packages/getting-started) tutorial for a step-by-step guide on how to use Buildkite Packages.
-
-If you're familiar with the basics, explore how to use registries for each of Buildkite Packages' supported package ecosystems:
-
-
-
-
- <%= button ":alpine: Alpine (apk)", "/docs/packages/alpine" %>
- <%= button ":docker: Container (Docker)", "/docs/packages/container" %>
- <%= button ":debian: Debian/Ubuntu (deb)", "/docs/packages/debian" %>
- <%= button ":helm: Helm (OCI)", "/docs/packages/helm-oci" %>
- <%= button ":helm: Helm", "/docs/packages/helm" %>
- <%= button ":maven: Java (Maven)", "/docs/packages/maven" %>
- <%= button ":gradle: Java (Gradle)", "/docs/packages/gradle" %>
- <%= button ":node: JavaScript (npm)", "/docs/packages/javascript" %>
- <%= button ":python: Python (PyPI)", "/docs/packages/python" %>
- <%= button ":redhat: Red Hat (RPM)", "/docs/packages/red-hat" %>
- <%= button ":ruby: Ruby (RubyGems)", "/docs/packages/ruby" %>
- <%= button ":terraform: Terraform (modules)", "/docs/packages/terraform" %>
- <%= button ":package: Files (generic)", "/docs/packages/files" %>
-
-
-
-
-Learn more about how to:
-
-- Work with Buildkite Packages registries in [Manage registries](/docs/packages/manage-registries).
-- Manage access to your registries in [User, team, and registry permissions](/docs/packages/permissions).
-- Configure your own private storage for Buildkite Packages in [Private storage](/docs/packages/private-storage).
diff --git a/pages/packages/ecosystems.md b/pages/packages/ecosystems.md
deleted file mode 100644
index a2197c1ffd..0000000000
--- a/pages/packages/ecosystems.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Package ecosystems overview
-
-Buildkite Packages supports the following language and package ecosystems:
-
-<%= render_markdown partial: 'packages/supported_package_ecosystems' %>
diff --git a/pages/packages/security.md b/pages/packages/security.md
deleted file mode 100644
index f65db01a9b..0000000000
--- a/pages/packages/security.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-toc: false
----
-
-# Security
-
-Customer security is paramount to Buildkite. Buildkite Packages provides mechanisms to restrict access to your registries from Buildkite Agents and their pipeline's jobs, as well as other third-party systems that can issue [Open ID Connect (OIDC)](https://openid.net/developers/how-connect-works/) tokens.
-
-Learn more about OIDC tokens and defining OIDC policies for registries in [OIDC with Buildkite Packages](/docs/packages/security/oidc).
diff --git a/pages/pipelines/migrate_from_jenkins.md b/pages/pipelines/migrate_from_jenkins.md
index 4f06a4cae1..ec7656f103 100644
--- a/pages/pipelines/migrate_from_jenkins.md
+++ b/pages/pipelines/migrate_from_jenkins.md
@@ -200,4 +200,4 @@ Remember that it may take some time to adapt to the new platform, and be prepare
If you need further assistance or have any questions, please don't hesitate to reach out to [support](https://buildkite.com/support). We're here to help you use Buildkite to build your dream CI/CD workflows.
-After configuring Buildkite Pipelines for your team, you could get actionable insights from the tests running in pipelines using [Test Analytics](/docs/test-analytics).
+After configuring Buildkite Pipelines for your team, you could get actionable insights from the tests running in pipelines using [Test Engine](/docs/test-engine).
diff --git a/pages/pipelines/security/audit_log.md b/pages/pipelines/security/audit_log.md
index 336b49a15c..38f04c034f 100644
--- a/pages/pipelines/security/audit_log.md
+++ b/pages/pipelines/security/audit_log.md
@@ -150,7 +150,7 @@ TEAM_PIPELINE_DELETED
TEAM_PIPELINE_UPDATED
```
-#### For Buildkite Packages
+#### For Buildkite Package Registries
```
TEAM_REGISTRY_CREATED
@@ -158,7 +158,7 @@ TEAM_REGISTRY_UPDATED
TEAM_REGISTRY_DELETED
```
-#### For Buildkite Test Analytics
+#### For Buildkite Test Engine
```
TEAM_SUITE_CREATED
@@ -192,7 +192,7 @@ SCM_PIPELINE_SETTINGS_DELETED
SCM_PIPELINE_SETTINGS_UPDATED
```
-### Test Analytics
+### Test Engine
```
SUITE_API_TOKEN_REGENERATED_EVENT
@@ -239,7 +239,7 @@ CLUSTER_PERMISSION_CREATED
CLUSTER_PERMISSION_DELETED
```
-### Buildkite Packages
+### Buildkite Package Registries
```
REGISTRY_CREATED
diff --git a/pages/pipelines/security/oidc.md b/pages/pipelines/security/oidc.md
index 8f2764ca32..affd2b8dc3 100644
--- a/pages/pipelines/security/oidc.md
+++ b/pages/pipelines/security/oidc.md
@@ -6,7 +6,7 @@ keywords: oidc, authentication, IAM, roles
<%= render_markdown partial: 'platform/oidc_introduction' %>
-You can configure third-party products and services, such as [AWS](https://aws.amazon.com/), [GCP](https://cloud.google.com/), [Azure](https://azure.microsoft.com/) and many others, as well as Buildkite products, such as [Packages](/docs/packages/security/oidc), with OIDC policies that only permit Buildkite Agent interactions from specific Buildkite organizations, pipelines, agents, and other metadata associated with the pipeline's job.
+You can configure third-party products and services, such as [AWS](https://aws.amazon.com/), [GCP](https://cloud.google.com/), [Azure](https://azure.microsoft.com/) and many others, as well as Buildkite products, such as [Package Registries](/docs/package-registries/security/oidc), with OIDC policies that only permit Buildkite Agent interactions from specific Buildkite organizations, pipelines, agents, and other metadata associated with the pipeline's job.
A Buildkite OIDC token can be issued by a Buildkite Agent, asserting claims about the slugs of the pipeline it is building and organization that contains this pipeline, the ID of the job that created the token, as well as other claims, such as the name of the branch used in the build, the SHA of the commit that triggered the build, and the agent ID. Such a token is associated with a Buildkite Agent interaction to perform one or more actions within the third-party service. If the token's claims do not comply with the service's OIDC policy, the token is rejected and subsequent pipeline jobs' interactions are rejected.
diff --git a/pages/pipelines/security/permissions.md b/pages/pipelines/security/permissions.md
new file mode 100644
index 0000000000..edd517025a
--- /dev/null
+++ b/pages/pipelines/security/permissions.md
@@ -0,0 +1,82 @@
+# User, team, and pipeline permissions
+
+Customers on the Buildkite [Pro and Enterprise](https://buildkite.com/pricing) plans can manage registry permissions using the [_teams_ feature](#manage-teams-and-permissions). This feature allows you to apply access permissions and functionality controls for one or more groups of users (that is, _teams_) on each pipeline throughout your organization.
+
+Enterprise customers can configure pipeline permissions for all users across their Buildkite organization through the **Security** page. Learn more about this feature in [Manage organization security for pipelines](#manage-organization-security-for-pipelines).
+
+## Manage teams and permissions
+
+To manage teams across the Buildkite Pipelines application, a _Buildkite organization administrator_ first needs to enable this feature across their organization. Learn more about how to do this in the [Manage teams and permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions).
+
+Once the _teams_ feature is enabled, you can see the teams that you're a member of from the **Users** page, which:
+
+- As a Buildkite organization administrator, you can access by selecting **Settings** in the global navigation > [**Users**](https://buildkite.com/organizations/~/users/).
+
+- As any other user, you can access by selecting **Teams** in the global navigation > [**Users**](https://buildkite.com/organizations/~/users/).
+
+### Organization-level permissions
+
+Learn more about what a _Buildkite organization administrator_ can do in the [Organization-level permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions-organization-level-permissions).
+
+As an organization administrator, you can access the [**Organization Settings** page](https://buildkite.com/organizations/~/settings) by selecting **Settings** in the global navigation, where you can do the following:
+
+- Add new teams or edit existing ones in the [**Team** section](https://buildkite.com/organizations/~/teams).
+
+- After selecting a team, you can view and administer the member-, [pipeline-](#manage-teams-and-permissions-pipeline-level-permissions), [test suite-](/docs/test-analytics/permissions#manage-teams-and-permissions-test-suite-level-permissions), [registry-](/docs/package-registries/security/permissions#manage-teams-and-permissions-registry-level-permissions) and [team-](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions)level settings for that team.
+
+**Note:** Registry-level settings are only available once [Buildkite Package Registries has been enabled](/docs/package-registries/security/permissions#enabling-buildkite-packages).
+
+### Team-level permissions
+
+Learn more about what _team members_ are and what _team maintainers_ can do in the [Team-level permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions).
+
+### Pipeline-level permissions
+
+When the [teams feature is enabled](#manage-teams-and-permissions), any user can create a new pipeline, as long as this user is a member of at least one team within the Buildkite organization, and this team has the **Create pipelines** [team member permission](#manage-teams-and-permissions-team-level-permissions).
+
+When you create a new pipeline in Buildkite:
+
+- You are automatically granted the **Full Access** (`MANAGE_BUILD_AND_READ`) permission to this pipeline.
+- Any members of teams to which you provide access to this pipeline are also granted the **Full Access** permission.
+
+**Full Access** on a pipeline allows you to:
+
+- View and create builds or rebuilds.
+- Edit pipeline settings, which includes the ability to change the pipeline's visibility.
+- Archive the pipeline or delete the pipeline.
+- Provide access to other users, by adding the pipeline to other teams that you are a [team maintainer](#manage-teams-and-permissions-team-level-permissions) on.
+
+Any user with the **Full Access** permission on a pipeline can change its permission to either:
+
+- **Build & Read** (`BUILD_AND_READ`), which allows you to view and create builds or rebuilds, but _not_:
+ * Edit the pipeline settings.
+ * Archive or delete the pipeline.
+ * Provide access to other users.
+- **Read Only** (`READ_ONLY`), which allows you to view builds only, but _not_:
+ * Create builds or issue rebuilds.
+ * Edit the pipeline settings.
+ * Archive or delete the pipeline.
+ * Provide access to other users.
+
+A user who is a member of at least one team with **Full Access** permission to a pipeline can change the permission on this pipeline. However, once this user loses **Full Access** through their last team with this permission on this pipeline, the user then loses the ability to change the pipeline's permissions in any team they are a member of.
+
+Another user with **Full Access** to this pipeline or a [Buildkite organization administrator](#manage-teams-and-permissions-organization-level-permissions) is required to change the pipeline's permission back to **Full Access** again.
+
+## Manage organization security for pipelines
+
+Enterprise customers can configure pipeline action permissions and related security features for all users across their Buildkite organization. These features can be used either with or without the [teams feature enabled](#manage-teams-and-permissions).
+
+These user-level permissions and security features are managed by _Buildkite organization administrators_. To access this feature:
+
+1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page.
+
+1. Select [**Security** > **Pipelines** tab](https://buildkite.com/organizations/~/security/pipelines) to access your organization's security for pipelines page.
+
+From this page, you can configure the following permissions for all users across your Buildkite organization:
+
+- **Create Pipelines**βif the [teams feature](#manage-teams-and-permissions) is enabled, then this permission is controlled at a [team-level](#manage-teams-and-permissions-team-level-permissions) and therefore, this option will be unavailable on this page.
+- **Delete pipelines**
+- **Change Pipeline Visibility**βMake private pipelines publicly available.
+- **Change Notification Services**βAllows notification services to be created, edited, and deleted.
+- **Manage Agent Registration Tokens**βAllows [agent tokens](/docs/agent/v3/tokens) to be created, edited, and deleted.
+- **Stop Agents**βAllows users to disconnect agents from Buildkite.
diff --git a/pages/pipelines/security/secrets/managing.md b/pages/pipelines/security/secrets/managing.md
index 3aef4d409f..ea998a4f78 100644
--- a/pages/pipelines/security/secrets/managing.md
+++ b/pages/pipelines/security/secrets/managing.md
@@ -36,7 +36,7 @@ By default, the `environment` hook file is stored in the agent's `hooks` directo
The path to this directory varies by platform; read the [installation instructions](/docs/agent/v3/installation) for the path on your platform.
The path can also be overridden by the [`hooks-path`](/docs/agent/v3/hooks#hook-locations-agent-hooks) setting.
-For example, to expose a Test Analytics API token to a specific pipeline, create an `environment` script in your agent's `hooks` directory that checks for the pipeline slug before exporting the secret:
+For example, to expose a Test Engine API token to a specific pipeline, create an `environment` script in your agent's `hooks` directory that checks for the pipeline slug before exporting the secret:
```bash
#!/bin/bash
diff --git a/pages/platform.md b/pages/platform.md
new file mode 100644
index 0000000000..ec2fbb34a6
--- /dev/null
+++ b/pages/platform.md
@@ -0,0 +1,15 @@
+---
+template: "landing_page"
+---
+
+# The Buildkite platform
+
+The Buildkite Scale-Out Delivery Platform is an adaptable, composable, and scalable platform with everything platform teams need to build software delivery systems for their businessesβand rapidly deliver value to users.
+
+The Buildkite platform documentation contains docs for _platform_-level features of Buildkite available across Buildkite [Pipelines](/docs/pipelines), [Test Engine](/docs/test-engine), as well as [Package Registries](/docs/package-registries). This area of the docs covers the following topics:
+
+- [Team management](/docs/team-management), with guidelines on how to manage your users and teams across the Buildkite platform for Pipelines, Test Engine, and Package Registries.
+
+- [Buildkite CLI](/docs/cli), which provides command line/terminal access to work with features across the Buildkite platform.
+
+- [Single sign-on (SSO)](/docs/integrations/sso), with guidelines on how to protect access to your Buildkite organization using a supported third-party SSO provider.
diff --git a/pages/team_management.md b/pages/team_management.md
index 5aaec37e9d..aa7594653f 100644
--- a/pages/team_management.md
+++ b/pages/team_management.md
@@ -4,7 +4,7 @@ toc: false
# Team management
-Managing users and teams in CI/CD is fundamental to collaboration, streamlined processes, and ensuring adequate access controls. Buildkite provides features to manage team access:
+Managing users and teams across your CI/CD platform is fundamental to collaboration, streamlined processes, and ensuring adequate access controls. Buildkite provides features to manage team access:
- [User and team permissions](/docs/team-management/permissions)
- [Enforce 2FA](/docs/team-management/enforce-2fa)
diff --git a/pages/team_management/permissions.md b/pages/team_management/permissions.md
index 7e64b916e7..8f002aa16b 100644
--- a/pages/team_management/permissions.md
+++ b/pages/team_management/permissions.md
@@ -2,8 +2,6 @@
Customers on the Buildkite [Pro and Enterprise](https://buildkite.com/pricing) plans can manage permissions using the _teams_ feature. Learn more about this feature in [Manage teams and permissions](#manage-teams-and-permissions).
-Enterprise customers can configure pipeline permissions and security features for all users across their Buildkite organization through the **Security** page. Learn more about this feature in [Manage organization security for pipelines](#manage-organization-security-for-pipelines).
-
## Manage teams and permissions
The _teams_ feature allows you to apply access permissions and functionality controls for one or more groups of users (that is, _teams_) on each pipeline, test suite, registry, or any combination of these, throughout your organization.
@@ -33,16 +31,16 @@ A user who is a _Buildkite organization administrator_ can access the [**Organiz
- From the **Teams** page:
* Create a new team, using the **New Team** button.
- * Administer (with full control) the [team-](#manage-teams-and-permissions-team-level-permissions), [pipeline-](#manage-teams-and-permissions-pipeline-level-permissions), [test suite-](/docs/test-analytics/permissions#manage-teams-and-permissions-test-suite-level-permissions) and [registry-](/docs/packages/permissions#manage-teams-and-permissions-registry-level-permissions)level settings throughout their Buildkite organization.
+ * Administer (with full control) the [team-](#manage-teams-and-permissions-team-level-permissions), [pipeline-](/docs/pipelines/security/permissions#manage-teams-and-permissions-pipeline-level-permissions), [test suite-](/docs/test-engine/permissions#manage-teams-and-permissions-test-suite-level-permissions) and [registry-](/docs/package-registries/security/permissions#manage-teams-and-permissions-registry-level-permissions)level settings throughout their Buildkite organization.
- **Note:** Registry-level settings are only available once [Buildkite Packages has been enabled](/docs/packages/permissions#enabling-buildkite-packages).
+ **Note:** Registry-level settings are only available once [Buildkite Package Registries has been enabled](/docs/package-registries/security/permissions#enabling-buildkite-packages).
* Delete an existing team, by selecting the team > **Settings** tab > **Delete Team** button.
* [Enable](#manage-teams-and-permissions) and disable the teams feature for their organization. This feature can only be disabled once all teams have been deleted from the organization (including the automatically-created **Everyone** team) using the **Disable Teams** button on the **Teams** page. Once the teams feature has been disabled, it can be [re-enabled](#manage-teams-and-permissions) at any time.
-- Configure other organization-level settings for Buildkite Pipelines and Packages, as well as various [integrations](/docs/integrations) with Buildkite.
+- Configure other organization-level settings for Buildkite Pipelines and Package Registries, as well as various [integrations](/docs/integrations) with Buildkite.
-- Access and view Buildkite Pipelines and Packages usage reports and [audit logs](/docs/pipelines/security/audit-log).
+- Access and view Buildkite Pipelines and Package Registries usage reports and [audit logs](/docs/pipelines/security/audit-log).
### Team-level permissions
@@ -59,13 +57,13 @@ A user who is a _team maintainer_ on an existing team can:
* Remove a user from this team, by selecting the user's **Remove** button.
* Change the permission for all users in this team on any:
- - [pipeline](#manage-teams-and-permissions-pipeline-level-permissions) in the team to **Full Access**, **Build & Read** or **Read Only**.
- - [test suite](/docs/test-analytics/permissions#manage-teams-and-permissions-test-suite-level-permissions) in the team to **Full Access** or **Read Only**.
- - [registry](/docs/packages/permissions#manage-teams-and-permissions-registry-level-permissions) in the team to **Full Access**, **Read & Write** or **Read Only**.
+ - [pipeline](/docs/pipelines/security/permissions#manage-teams-and-permissions-pipeline-level-permissions) in the team to **Full Access**, **Build & Read** or **Read Only**.
+ - [test suite](/docs/test-engine/permissions#manage-teams-and-permissions-test-suite-level-permissions) in the team to **Full Access** or **Read Only**.
+ - [registry](/docs/package-registries/security/permissions#manage-teams-and-permissions-registry-level-permissions) in the team to **Full Access**, **Read & Write** or **Read Only**.
To do this, select the appropriate tab (**Pipelines**, **Test Suites** or **Package Registries**) and then select the required permission for the item, although be aware of the [caveat below](#changing-full-access-permissions-on-pipelines-test-suites-and-registries).
- **Note:** Managing team permissions for registries is only available once [Buildkite Packages has been enabled](/docs/packages/permissions#enabling-buildkite-packages).
+ **Note:** Managing team permissions for registries is only available once [Buildkite Package Registries has been enabled](/docs/package-registries/security/permissions#enabling-buildkite-packages).
* Edit the team's details and other settings using the **Settings** tab, which includes the ability to:
@@ -86,44 +84,12 @@ A user who is a _team maintainer_ on an existing team can:
As indicated in the Buildkite interface, a user who is in a team is known as a **Team Member**, and such users have fewer permissions within the team (that is, no team management capabilities) than a **Team Maintainer**.
-All team members in a team have the same level of access to the [pipelines](#manage-teams-and-permissions-pipeline-level-permissions), [test suites](/docs/test-analytics/permissions#manage-teams-and-permissions-test-suite-level-permissions), and [registries](/docs/packages/permissions#manage-teams-and-permissions-registry-level-permissions) in the team. If you need to have more fine grained control over the pipelines, test suites or registries in a team, you can create more teams with different permissions.
+All team members in a team have the same level of access to the [pipelines](/docs/pipelines/security/permissions#manage-teams-and-permissions-pipeline-level-permissions), [test suites](/docs/test-engine/permissions#manage-teams-and-permissions-test-suite-level-permissions), and [registries](/docs/package-registries/security/permissions#manage-teams-and-permissions-registry-level-permissions) in the team. If you need to have more fine grained control over the pipelines, test suites or registries in a team, you can create more teams with different permissions.
> π§ Changing **Full Access** permissions on pipelines, test suites and registries
> As a team maintainer, once you change the permission on any of these items away from **Full Access**, you could lose the ability to change the permissions on that item again. This can happen if you are no longer a member of a team that provides **Full Access** to this item.
> A [Buildkite organization administrator](#manage-teams-and-permissions-organization-level-permissions) is required to change any item's permissions back to **Full Access** again.
-### Pipeline-level permissions
-
-When the [teams feature is enabled](#manage-teams-and-permissions), any user can create a new pipeline, as long as this user is a member of at least one team within the Buildkite organization, and this team has the **Create pipelines** [team member permission](#manage-teams-and-permissions-team-level-permissions).
-
-When you create a new pipeline in Buildkite:
-
-- You are automatically granted the **Full Access** (`MANAGE_BUILD_AND_READ`) permission to this pipeline.
-- Any members of teams to which you provide access to this pipeline are also granted the **Full Access** permission.
-
-**Full Access** on a pipeline allows you to:
-
-- View and create builds or rebuilds.
-- Edit pipeline settings, which includes the ability to change the pipeline's visibility.
-- Archive the pipeline or delete the pipeline.
-- Provide access to other users, by adding the pipeline to other teams that you are a [team maintainer](#manage-teams-and-permissions-team-level-permissions) on.
-
-Any user with the **Full Access** permission on a pipeline can change its permission to either:
-
-- **Build & Read** (`BUILD_AND_READ`), which allows you to view and create builds or rebuilds, but _not_:
- * Edit the pipeline settings.
- * Archive or delete the pipeline.
- * Provide access to other users.
-- **Read Only** (`READ_ONLY`), which allows you to view builds only, but _not_:
- * Create builds or issue rebuilds.
- * Edit the pipeline settings.
- * Archive or delete the pipeline.
- * Provide access to other users.
-
-A user who is a member of at least one team with **Full Access** permission to a pipeline can change the permission on this pipeline. However, once this user loses **Full Access** through their last team with this permission on this pipeline, the user then loses the ability to change the pipeline's permissions in any team they are a member of.
-
-Another user with **Full Access** to this pipeline or a [Buildkite organization administrator](#manage-teams-and-permissions-organization-level-permissions) is required to change the pipeline's permission back to **Full Access** again.
-
### Programmatically managing teams
You can programmatically manage your teams using our GraphQL API.
@@ -207,25 +173,6 @@ mutation RemoveOrganizationMember {
}
```
-## Manage organization security for pipelines
-
-Enterprise customers can configure pipeline action permissions and related security features for all users across their Buildkite organization. These features can be used either with or without the [teams feature enabled](#manage-teams-and-permissions).
-
-These user-level permissions and security features are managed by _Buildkite organization administrators_. To access this feature:
-
-1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page.
-
-1. Select [**Security** > **Pipelines** tab](https://buildkite.com/organizations/~/security/pipelines) to access your organization's security for pipelines page.
-
-From this page, you can configure the following permissions for all users across your Buildkite organization:
-
-- **Create Pipelines**βif the [teams feature](#manage-teams-and-permissions) is enabled, then this permission is controlled at a [team-level](#manage-teams-and-permissions-team-level-permissions) and therefore, this option will be unavailable on this page.
-- **Delete pipelines**
-- **Change Pipeline Visibility**βMake private pipelines publicly available.
-- **Change Notification Services**βAllows notification services to be created, edited, and deleted.
-- **Manage Agent Registration Tokens**βAllows [agent tokens](/docs/agent/v3/tokens) to be created, edited, and deleted.
-- **Stop Agents**βAllows users to disconnect agents from Buildkite.
-
## Removing users during a security incident
If you believe that a user account has been compromised, the recommended incident response is to remove such a user from your Buildkite organization immediately. This will entirely remove their ability to impact your organization and protect you from any further actions that the user could take.
diff --git a/pages/test_analytics.md b/pages/test_analytics.md
deleted file mode 100644
index bde6c54a6a..0000000000
--- a/pages/test_analytics.md
+++ /dev/null
@@ -1,52 +0,0 @@
----
-template: "landing_page"
----
-
-# Buildkite Test Analytics
-
-Where Buildkite Pipelines help you automate your build pipelines,
-Test Analytics helps you track and analyze the steps in that pipeline that involve tests:
-
-- Ship code to production faster by optimizing test suites
-- Works with any continuous integration
-- Identify, fix, and monitor test suite performance
-- Track, improve, and monitor test suite reliability
-
-<%= image "overview.png", width: 975, height: 205, alt: "Screenshot of test suite trend showing five metrics over 28 days" %>
-
-## Get started
-
-
-
-
- <%= button ":rspec: RSpec", "/docs/test-analytics/ruby-collectors#rspec-collector" %>
- <%= button ":ruby: minitest", "/docs/test-analytics/ruby-collectors#minitest-collector" %>
- <%= button ":jest: Jest", "/docs/test-analytics/javascript-collectors#configure-the-test-framework-jest" %>
- <%= button ":mocha: Mocha", "/docs/test-analytics/javascript-collectors#configure-the-test-framework-mocha" %>
- <%= button ":cypress: Cypress", "/docs/test-analytics/javascript-collectors#configure-the-test-framework-cypress" %>
- <%= button ":jasmine: Jasmine", "/docs/test-analytics/javascript-collectors#configure-the-test-framework-jasmine" %>
- <%= button ":playwright: Playwright", "/docs/test-analytics/javascript-collectors#configure-the-test-framework-playwright" %>
- <%= button ":swift: Swift", "/docs/test-analytics/swift-collectors" %>
- <%= button ":android: Android", "/docs/test-analytics/android-collectors" %>
- <%= button ":pytest: pytest", "/docs/test-analytics/python-collectors" %>
- <%= button ":golang: Go", "/docs/test-analytics/golang-collectors" %>
- <%= button ":junit: JUnit", "/docs/test-analytics/importing-junit-xml" %>
- <%= button ":dotnet: .NET", "/docs/test-analytics/dotnet-collectors" %>
- <%= button ":elixir: Elixir", "/docs/test-analytics/elixir-collectors" %>
- <%= button ":rust: Rust", "/docs/test-analytics/rust-collectors" %>
-
-
-
-
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
-
->π Data retention
-> The data uploaded to Test Analytics is stored in S3 and deleted after six months.
-
-----
-
-<%= tiles "test_analytics_features" %>
-
-----
-
-<%= tiles "test_analytics_guides" %>
diff --git a/pages/test_analytics/other_collectors.md b/pages/test_analytics/other_collectors.md
deleted file mode 100644
index c19815ac59..0000000000
--- a/pages/test_analytics/other_collectors.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-toc: false
----
-
-# Collecting data from other test frameworks
-
-You can integrate any language and framework by uploading [Test Analytics JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml) after your tests run. You can also [build your own collector](/docs/test-analytics/your-own-collectors).
diff --git a/pages/test_analytics/test_executions.md b/pages/test_analytics/test_executions.md
deleted file mode 100644
index 9823eac0b1..0000000000
--- a/pages/test_analytics/test_executions.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Test executions
-
-Each [Buildkite plan](https://buildkite.com/pricing) has test execution inclusions, which vary depending on the plan type and the number of users in your organization.
-
-You can find the test execution details for a run at the bottom of the run page, and your organization's [total usage](#usage-page) in Settings.
-<%= image "test_executions.png", alt: "Test executions run page" %>
-
-## Usage page
-
-The [Usage page](https://buildkite.com/organizations/~/usage) is available on every Buildkite plan and shows a breakdown of job minutes and test executions for your organization.
-
-The [test executions usage page](https://buildkite.com/organizations/~/usage/test_executions) graphs the total executions over the organization's billing periods. It includes a breakdown of usage by suite and a CSV download of usage over the period.
-
-Your organization's usage is also accessible in the [GraphQL API](/docs/apis/graphql/cookbooks/organizations#query-the-usage-api).
diff --git a/pages/test_analytics/test_splitting.md b/pages/test_analytics/test_splitting.md
deleted file mode 100644
index da78ad0ac3..0000000000
--- a/pages/test_analytics/test_splitting.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Configuring test splitting
-
-Test splitting is the process of partitioning a test suite to run in parallel across multiple Buildkite agents. Buildkite maintains its open source Test Splitter ([test-splitter](https://github.com/buildkite/test-splitter)) tool. This tool uses your Buildkite Test Analytics test suite data to intelligently partition tests throughout your test suite into multiple sets, such that each set of tests runs in parallel across your agents. This process is known as _orchestration_ and results in a _test plan_, where a test plan defines which tests are run on which agents. Currently, the Test Splitter tool only supports RSpec.
-
-## Dependencies
-
-The Test Splitter relies on execution timing data captured by the Buildkite test collectors from previous builds to partition your tests evenly across your agents. Therefore, you will need to configure the [Ruby test collector](./ruby-collectors) for your test suite.
-
-## Installation
-
-The [latest version of test-splitter](https://github.com/buildkite/test-splitter/releases) can be downloaded from GitHub for installation to your agent/s. Binaries are available for both Mac and Linux with 64-bit ARM and AMD architectures. Download the executable and make it available in your testing environment.
-
-## Using the test splitter
-
-Once you have downloaded the test-splitter binary and it's executable in your Buildkite pipeline, you'll need to configure some additional environment variables for the test splitter to function. You can then update your pipeline step to call test-splitter instead of calling RSpec to run your tests.
-
-### Configure environment variables
-
-The Test Splitter tool uses a number of [predefined](#predefined-environment-variables), [mandatory](#mandatory-environment-variables), and [optional](#optional-environment-variables) environment variables.
-
-
-
-#### Predefined environment variables
-
-By default, the following predefined environment variables are available to your testing environment and do not need any further configuration. If, however, you use Docker or some other type of containerization tool to run your tests, and you wish to use these predefined environment variables in these tests, you may need to expose these environment variables to your containers.
-
-
-
- <% TEST_SPLITTING_ENV['predefined'].each do |var| %>
-
-
- <%= var['name'] %> #
- |
-
- <% var['desc'].each do |d| %>
- <%= render_markdown(text: d) %>
- <% end %>
- |
-
- <% end %>
-
-
-
-
-
-#### Mandatory environment variables
-
-The following mandatory environment variables must be set.
-
-
-
- <% TEST_SPLITTING_ENV['mandatory'].each do |var| %>
-
-
- <%= var['name'] %> #
- |
-
- <% var['desc'].each do |d| %>
- <%= render_markdown(text: d) %>
- <% end %>
- |
-
- <% end %>
-
-
-
-
-
-#### Optional environment variables
-
-The following optional environment variables can also be used to configure the Test Splitter's behavior.
-
-
-
- <% TEST_SPLITTING_ENV['optional'].each do |var| %>
-
-
- <%= var['name'] %> #
-
- Default:
- <%= var['default'] %>
-
- |
-
- <% var['desc'].each do |d| %>
- <%= render_markdown(text: d) %>
- <% end %>
- |
-
- <% end %>
-
-
-
-
-### Update the pipeline step
-
-With the environment variables configured, you can now update your pipeline step to use test-splitter instead of running RSpec. The following example pipeline step demonstrates how to partition your test suite across 10 nodes.
-
-```
-steps:
- - name: "RSpec"
- command: ./test-splitter
- parallelism: 10
- env:
- BUILDKITE_SPLITTER_SUITE_SLUG: my-suite
- BUILDKITE_SPLITTER_API_ACCESS_TOKEN: your-secret-token
-```
-{: codeblock-file="pipeline.yml"}
diff --git a/pages/test_analytics/your_own_collectors.md b/pages/test_analytics/your_own_collectors.md
deleted file mode 100644
index 208854dcca..0000000000
--- a/pages/test_analytics/your_own_collectors.md
+++ /dev/null
@@ -1,9 +0,0 @@
----
-toc: false
----
-
-# Your own collectors
-
-Test Analytics integrates directly with your test runner to provide in-depth information about your tests (including spans) in real time.
-
-If you're interested in building your own fully integrated analytics collector for specific test runners, have a look at our [example collector](https://github.com/buildkite/rspec-buildkite-analytics) on GitHub.
diff --git a/pages/test_engine.md b/pages/test_engine.md
new file mode 100644
index 0000000000..b237a46177
--- /dev/null
+++ b/pages/test_engine.md
@@ -0,0 +1,57 @@
+---
+template: "landing_page"
+---
+
+# Buildkite Test Engine
+
+Scale out your testing across any framework with _Buildkite Test Engine_. Speed up builds with real-time flaky test management and intelligent test splitting. Drive accountability and get more out of your existing CI compute with performance insights and analytics.
+
+Where [Buildkite Pipelines](/docs/pipelines) helps you automate your CI/CD pipelines, Test Engine helps you track and analyze the steps in these pipelines, by:
+
+- Shipping code to production faster through test suite optimization.
+- Working directly with Buildkite Pipelines, as well as other CI/CD applications.
+- Identifying, fixing, and monitoring test suite performance.
+- Tracking, improving, and monitoring test suite reliability.
+
+<%= image "overview.png", width: 975, height: 205, alt: "Screenshot of test suite trend showing five metrics over 28 days" %>
+
+_Buildkite Test Engine_ was previously called _Buildkite Test Analytics_.
+
+## Get started
+
+To get started with Test Engine, and to begin setting up your _test suites_, configure the relevant supported _test collectors_ for your development project.
+
+
+
+
+ <%= button ":rspec: RSpec", "/docs/test-engine/ruby-collectors#rspec-collector" %>
+ <%= button ":ruby: minitest", "/docs/test-engine/ruby-collectors#minitest-collector" %>
+ <%= button ":jest: Jest", "/docs/test-engine/javascript-collectors#configure-the-test-framework-jest" %>
+ <%= button ":mocha: Mocha", "/docs/test-engine/javascript-collectors#configure-the-test-framework-mocha" %>
+ <%= button ":cypress: Cypress", "/docs/test-engine/javascript-collectors#configure-the-test-framework-cypress" %>
+ <%= button ":jasmine: Jasmine", "/docs/test-engine/javascript-collectors#configure-the-test-framework-jasmine" %>
+ <%= button ":playwright: Playwright", "/docs/test-engine/javascript-collectors#configure-the-test-framework-playwright" %>
+ <%= button ":swift: Swift", "/docs/test-engine/swift-collectors" %>
+ <%= button ":android: Android", "/docs/test-engine/android-collectors" %>
+ <%= button ":pytest: pytest", "/docs/test-engine/python-collectors" %>
+ <%= button ":golang: Go", "/docs/test-engine/golang-collectors" %>
+ <%= button ":junit: JUnit", "/docs/test-engine/importing-junit-xml" %>
+ <%= button ":dotnet: .NET", "/docs/test-engine/dotnet-collectors" %>
+ <%= button ":elixir: Elixir", "/docs/test-engine/elixir-collectors" %>
+ <%= button ":rust: Rust", "/docs/test-engine/rust-collectors" %>
+
+
+
+
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
+
+Once your test collectors have been set up, you can begin configuring your test suites by running through the relevant 'Getting started' sections, beginning with [Configuring test suites](/docs/test-engine/test-suites) for an overview of Test Engine's concepts and functionality.
+
+
+
+<%= tiles "test_engine_features" %>
+
+> π Data retention
+> The data uploaded to Test Engine is stored in S3 and deleted after six months.
+
+<%= tiles "test_engine_guides" %>
diff --git a/pages/test_analytics/android_collectors.md b/pages/test_engine/android_collectors.md
similarity index 77%
rename from pages/test_analytics/android_collectors.md
rename to pages/test_engine/android_collectors.md
index 1a641cf272..1f6b1e0a97 100644
--- a/pages/test_analytics/android_collectors.md
+++ b/pages/test_engine/android_collectors.md
@@ -4,15 +4,15 @@ toc: false
# Android collectors
-To use Test Analytics with your Android projects use the :github: [`test-collector-android`](https://github.com/buildkite/test-collector-android) package.
+To use Test Engine with your Android projects use the :github: [`test-collector-android`](https://github.com/buildkite/test-collector-android) package.
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
## Android
-Before you start, make sure your tests run with access to [CI environment variables](/docs/test-analytics/ci-environments).
+Before you start, make sure your tests run with access to [CI environment variables](/docs/test-engine/ci-environments).
-1. [Create a test suite](https://buildkite.com/docs/test-analytics) and copy the test suite API token.
+1. [Create a test suite](https://buildkite.com/docs/test-engine) and copy the test suite API token.
1. [Securely](/docs/pipelines/security/secrets/managing) set the `BUILDKITE_ANALYTICS_TOKEN` secret on your CI to the API token from the previous step.
@@ -89,14 +89,14 @@ Before you start, make sure your tests run with access to [CI environment variab
1. Commit and push your changes:
```bash
- git checkout -b add-buildkite-test-analytics
- git commit -am "Add Buildkite Test Analytics"
- git push origin add-buildkite-test-analytics
+ git checkout -b add-buildkite-test-engine
+ git commit -am "Add Buildkite Test Engine"
+ git push origin add-buildkite-test-engine
```
-Once you're done, in your Test Analytics dashboard, you'll see analytics of test executions on all branches that include this code.
+Once you're done, in your Test Engine dashboard, you'll see analytics of test executions on all branches that include this code.
-If you don't see branch names, build numbers, or commit hashes in Test Analytics, then read [CI Environments](/docs/test-analytics/ci-environments) to learn more about exporting your environment to the collector.
+If you don't see branch names, build numbers, or commit hashes in Test Engine, then read [CI Environments](/docs/test-engine/ci-environments) to learn more about exporting your environment to the collector.
### Debugging
diff --git a/pages/test_analytics/ci_environments.md b/pages/test_engine/ci_environments.md
similarity index 86%
rename from pages/test_analytics/ci_environments.md
rename to pages/test_engine/ci_environments.md
index eddab3d8e7..83ef11afa3 100644
--- a/pages/test_analytics/ci_environments.md
+++ b/pages/test_engine/ci_environments.md
@@ -1,16 +1,16 @@
# CI environments
-Buildkite Test Analytics collectors automatically detect common continuous integration (CI) environments.
+Buildkite Test Engine collectors automatically detect common continuous integration (CI) environments.
If available, test collectors gather information about your test runs, such as branch names and build IDs.
Test collectors gather information from the following CI environments:
-- [Buildkite](/docs/test-analytics/ci-environments#buildkite)
-- [CircleCI](/docs/test-analytics/ci-environments#circleci)
-- [GitHub Actions](/docs/test-analytics/ci-environments#github-actions)
+- [Buildkite](/docs/test-engine/ci-environments#buildkite)
+- [CircleCI](/docs/test-engine/ci-environments#circleci)
+- [GitHub Actions](/docs/test-engine/ci-environments#github-actions)
-If you run test collectors inside [containers](/docs/test-analytics/ci-environments#containers-and-test-collectors) or use another CI system, you must set variables to report your CI details to Buildkite.
+If you run test collectors inside [containers](/docs/test-engine/ci-environments#containers-and-test-collectors) or use another CI system, you must set variables to report your CI details to Buildkite.
-If you're not using a test collector, see [Importing JSON](/docs/test-analytics/importing-json) and [Importing JUnit XML](/docs/test-analytics/importing-junit-xml) to learn how to provide run environment data.
+If you're not using a test collector, see [Importing JSON](/docs/test-engine/importing-json) and [Importing JUnit XML](/docs/test-engine/importing-junit-xml) to learn how to provide run environment data.
## Recommended environment variables
@@ -103,9 +103,9 @@ run_env[key]=$GITHUB_ACTION-$GITHUB_RUN_NUMBER-$GITHUB_RUN_ATTEMPT
## Other CI providers
If you're using other CI providers (or [containers](#containers-and-test-collectors)), then set environment variables for test collectors to gather information about your builds and tests.
-If you don't set these environment variables, then Test Analytics lacks the details needed to produce useful reports.
+If you don't set these environment variables, then Test Engine lacks the details needed to produce useful reports.
-Each environment variable corresponds to a `run_env` key in the payload `https://analytics-api.buildkite.com/v1/uploads`. Read [Importing JSON](/docs/test-analytics/importing-json) to learn how these keys are used to make API calls.
+Each environment variable corresponds to a `run_env` key in the payload `https://analytics-api.buildkite.com/v1/uploads`. Read [Importing JSON](/docs/test-engine/importing-json) to learn how these keys are used to make API calls.
@@ -116,7 +116,7 @@ Each environment variable corresponds to a `run_env` key in the payload `https:/
- <% TEST_ANALYTICS_RUN_ENV['keys'].each do |key| -%>
+ <% TEST_ENGINE_RUN_ENV['keys'].each do |key| -%>
run_env[<%= key['name'] %>] |
<%= key['environment_variable'] %> |
diff --git a/pages/test_analytics/dotnet_collectors.md b/pages/test_engine/dotnet_collectors.md
similarity index 60%
rename from pages/test_analytics/dotnet_collectors.md
rename to pages/test_engine/dotnet_collectors.md
index 16aeb63f44..9d36baa63c 100644
--- a/pages/test_analytics/dotnet_collectors.md
+++ b/pages/test_engine/dotnet_collectors.md
@@ -4,13 +4,13 @@ toc: false
# .NET collector
-To use Test Analytics with your .NET projects use the :github: [`test-collector-dotnet`](https://github.com/buildkite/test-collector-dotnet) package with xUnit.
+To use Test Engine with your .NET projects use the :github: [`test-collector-dotnet`](https://github.com/buildkite/test-collector-dotnet) package with xUnit.
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
-Before you start, make sure .NET runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+Before you start, make sure .NET runs with access to [CI environment variables](/docs/test-engine/ci-environments).
-1. Create a [test suite](/docs/test-analytics/test-suites) and copy the API token that it gives you.
+1. Create a [test suite](/docs/test-engine/test-suites) and copy the API token that it gives you.
1. Add `Buildkite.TestAnalytics.Xunit` to your list of dependencies in your xUnit test project:
@@ -32,4 +32,4 @@ Before you start, make sure .NET runs with access to [CI environment variables](
1. Verify that it works
-If all is well, you should see the test run in the test analytics section of the Buildkite dashboard.
+If all is well, you should see the test run analytics on the Buildkite Test Engine dashboard.
diff --git a/pages/test_analytics/elixir_collectors.md b/pages/test_engine/elixir_collectors.md
similarity index 67%
rename from pages/test_analytics/elixir_collectors.md
rename to pages/test_engine/elixir_collectors.md
index f7ba088067..594b7943ff 100644
--- a/pages/test_analytics/elixir_collectors.md
+++ b/pages/test_engine/elixir_collectors.md
@@ -4,17 +4,17 @@ toc: false
# Elixir collectors
-To use Test Analytics with your Elixir projects use :github: [`test_collector_elixir`](https://github.com/buildkite/test_collector_elixir) with ExUnit.
+To use Test Engine with your Elixir projects use :github: [`test_collector_elixir`](https://github.com/buildkite/test_collector_elixir) with ExUnit.
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
## ExUnit
[ExUnit](https://hexdocs.pm/ex_unit/) is a Elixir unit test library.
-Before you start, make sure ExUnit runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+Before you start, make sure ExUnit runs with access to [CI environment variables](/docs/test-engine/ci-environments).
-1. Create a [test suite](/docs/test-analytics/test-suites) and copy the API token that it gives you.
+1. Create a [test suite](/docs/test-engine/test-suites) and copy the API token that it gives you.
1. Add `buildkite_test_collector` to your list of dependencies in `mix.exs`:
@@ -28,7 +28,7 @@ Before you start, make sure ExUnit runs with access to [CI environment variables
1. Set up your API token:
- In your `config/test.exs` (or other environment configuration as appropriate) add the analytics API token. We suggest that you retrieve the token from the environment, and configure your CI environment accordingly (for example using secrets).
+ In your `config/test.exs` (or other environment configuration as appropriate) add the Buildkite Test Engine API token. We suggest that you retrieve the token from the environment, and configure your CI environment accordingly (for example using secrets).
```elixir
import Config
@@ -60,4 +60,4 @@ Before you start, make sure ExUnit runs with access to [CI environment variables
Randomized with seed 12345
```
-1. Verify that it works. If all is well, you should see the test run in the test analytics section of the Buildkite dashboard.
+1. Verify that it works. If all is well, you should see the test run analytics on the Buildkite Test Engine dashboard.
diff --git a/pages/test_analytics/flaky_test_assignment.md b/pages/test_engine/flaky_test_assignment.md
similarity index 94%
rename from pages/test_analytics/flaky_test_assignment.md
rename to pages/test_engine/flaky_test_assignment.md
index a38135128e..77be705060 100644
--- a/pages/test_analytics/flaky_test_assignment.md
+++ b/pages/test_engine/flaky_test_assignment.md
@@ -1,6 +1,6 @@
# Flaky test assignment
-Customers on the [Pro and Enterprise plans](https://buildkite.com/pricing) can assign flaky tests to [teams](/docs/test-analytics/permissions#manage-teams-and-permissions).
+Customers on the [Pro and Enterprise plans](https://buildkite.com/pricing) can assign flaky tests to [teams](/docs/test-engine/permissions#manage-teams-and-permissions).
## Enabling flaky test assignments
@@ -36,6 +36,6 @@ When an assigned test has not flaked in more than 7 days, it is moved to the **O
## Weekly flaky test summary
-You're able to schedule a weekly summary of the flakiest tests assigned to your teams. Visit the **Suite settings** page to create new notifications, or manage existing ones. If you would like to set up auto assignment, check out our [Test ownership](/docs/test-analytics/test-ownership) feature.
+You're able to schedule a weekly summary of the flakiest tests assigned to your teams. Visit the **Suite settings** page to create new notifications, or manage existing ones. If you would like to set up auto assignment, check out our [Test ownership](/docs/test-engine/test-ownership) feature.
<%= image "flaky-test-summary-mailer.png", width: 1960/2, height: 630/2, alt: "Flaky test page showing team assignments" %>
diff --git a/pages/test_analytics/golang_collectors.md b/pages/test_engine/golang_collectors.md
similarity index 79%
rename from pages/test_analytics/golang_collectors.md
rename to pages/test_engine/golang_collectors.md
index 6610ba2812..e5cac9fef4 100644
--- a/pages/test_analytics/golang_collectors.md
+++ b/pages/test_engine/golang_collectors.md
@@ -2,9 +2,9 @@
toc: false
---
-# Configuring Go with Test Analytics
+# Configuring Go with Test Engine
-To use Test Analytics with your [Go](https://go.dev/) language projects use [gotestsum](https://github.com/gotestyourself/gotestsum) to generate JUnit XML files, then [upload the JUnit XML files](/docs/test-analytics/importing-junit-xml) to Test Analytics.
+To use Test Engine with your [Go](https://go.dev/) language projects use [gotestsum](https://github.com/gotestyourself/gotestsum) to generate JUnit XML files, then [upload the JUnit XML files](/docs/test-engine/importing-junit-xml) to Test Engine.
1. Install [gotestsum](https://github.com/gotestyourself/gotestsum):
diff --git a/pages/test_analytics/importing_json.md b/pages/test_engine/importing_json.md
similarity index 87%
rename from pages/test_analytics/importing_json.md
rename to pages/test_engine/importing_json.md
index 68e7f2ecb0..d9c7e5daf7 100644
--- a/pages/test_analytics/importing_json.md
+++ b/pages/test_engine/importing_json.md
@@ -1,16 +1,15 @@
# Importing JSON
-
-If a test collector is not available for your test framework, you can upload tests results directly to the Test Analytics API or [write your own test collector](/docs/test-analytics/your-own-collectors).
-You can upload JSON-formatted test results (described in this page) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+If a test collector is not available for your test framework, you can upload tests results directly to the Test Engine API or [write your own test collector](/docs/test-engine/your-own-collectors).
+You can upload JSON-formatted test results (described in this page) or [JUnit XML](/docs/test-engine/importing-junit-xml).
## How to import JSON in Buildkite
-It's possible to import JSON (or [JUnit](/docs/test-analytics/importing-junit-xml#how-to-import-junit-xml-in-buildkite) files) to Buildkite Test Analytics with or without the help of a plugin.
+It's possible to import JSON (or [JUnit](/docs/test-engine/importing-junit-xml#how-to-import-junit-xml-in-buildkite) files) to Buildkite Test Engine with or without the help of a plugin.
### Using a plugin
-To import [JSON-formatted test results](#json-test-results-data-reference) to Test Analytics using [Test Collector plugin](https://github.com/buildkite-plugins/test-collector-buildkite-plugin) from a build step:
+To import [JSON-formatted test results](#json-test-results-data-reference) to Test Engine using [Test Collector plugin](https://github.com/buildkite-plugins/test-collector-buildkite-plugin) from a build step:
```yml
steps:
@@ -35,7 +34,7 @@ To import [JSON-formatted test results](#json-test-results-data-reference) in Bu
For example, to import the contents of a [JSON-formatted test results](#json-test-results-data-reference) (`test-results.json`):
-1. Securely [set the Test Analytics token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
+1. Securely [set the Test Engine token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
2. Run the following `curl` command:
@@ -56,7 +55,7 @@ For example, to import the contents of a [JSON-formatted test results](#json-tes
https://analytics-api.buildkite.com/v1/uploads
```
-To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-analytics/ci-environments#buildkite).
+To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-engine/ci-environments#buildkite).
A single file can have a maximum of 5000 test results, and if that limit is exceeded then the upload request will fail. To upload more than 5000 test results for a single run upload multiple smaller files with the same `run_env[key]`.
@@ -66,7 +65,7 @@ To import [JSON-formatted test results](#json-test-results-data-reference), make
For example, to import the contents of a `test-results.json` file in a CircleCI pipeline:
-1. Securely [set the Test Analytics token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
+1. Securely [set the Test Engine token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
2. Run the following `curl` command:
@@ -85,7 +84,7 @@ For example, to import the contents of a `test-results.json` file in a CircleCI
https://analytics-api.buildkite.com/v1/uploads
```
-To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-analytics/ci-environments#circleci).
+To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-engine/ci-environments#circleci).
A single file can have a maximum of 5000 test results, and if that limit is exceeded then the upload request will fail. To upload more than 5000 test results for a single run upload multiple smaller files with the same `run_env[key]`.
@@ -95,7 +94,7 @@ To import [JSON-formatted test results](#json-test-results-data-reference), make
For example, to import the contents of a `test-results.json` file in a GitHub Actions pipeline run:
-1. Securely [set the Test Analytics token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
+1. Securely [set the Test Engine token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
2. Run the following `curl` command:
@@ -114,7 +113,7 @@ For example, to import the contents of a `test-results.json` file in a GitHub Ac
https://analytics-api.buildkite.com/v1/uploads
```
-To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-analytics/ci-environments#github-actions).
+To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-engine/ci-environments#github-actions).
A single file can have a maximum of 5000 test results, and if that limit is exceeded then the upload request will fail. To upload more than 5000 test results for a single run upload multiple smaller files with the same `run_env[key]`.
@@ -186,7 +185,7 @@ end
- <% TEST_ANALYTICS_JSON_FIELDS_TEST_RESULT['fields'].each do |field| -%>
+ <% TEST_ENGINE_JSON_FIELDS_TEST_RESULT['fields'].each do |field| -%>
<%= field['name'] %> <%= '(required)' if field['required'] %> |
<%= field['type'] %> <%= render_enumerated_values(field['enumerated_values']) %> |
@@ -234,7 +233,7 @@ A failure expanded array contains extra details about the failed test.
- <% TEST_ANALYTICS_JSON_FIELDS_FAILURE_EXPANDED['fields'].each do |field| -%>
+ <% TEST_ENGINE_JSON_FIELDS_FAILURE_EXPANDED['fields'].each do |field| -%>
<%= field['name'] %> <%= '(required)' if field['required'] %> |
<%= field['type'] %> <%= render_enumerated_values(field['enumerated_values']) %> |
@@ -283,7 +282,7 @@ A history object represents the overall duration of the test run and contains de
- <% TEST_ANALYTICS_JSON_FIELDS_HISTORY['fields'].each do |field| -%>
+ <% TEST_ENGINE_JSON_FIELDS_HISTORY['fields'].each do |field| -%>
<%= field['name'] %> <%= '(required)' if field['required'] %> |
<%= field['type'] %> <%= render_enumerated_values(field['enumerated_values']) %> |
@@ -322,7 +321,7 @@ It represents, for example, the duration of an individual database query within
- <% TEST_ANALYTICS_JSON_FIELDS_SPAN['fields'].each do |field| -%>
+ <% TEST_ENGINE_JSON_FIELDS_SPAN['fields'].each do |field| -%>
<%= field['name'] %> <%= '(required)' if field['required'] %> |
<%= field['type'] %> <%= render_enumerated_values(field['enumerated_values']) %> |
@@ -361,7 +360,7 @@ Detail objects contains additional information about the span.
- <% TEST_ANALYTICS_JSON_FIELDS_DETAIL['fields'].each do |field| -%>
+ <% TEST_ENGINE_JSON_FIELDS_DETAIL['fields'].each do |field| -%>
<%= field['name'] %> <%= '(required)' if field['required'] %> |
<%= field['type'] %> <%= render_enumerated_values(field['enumerated_values']) %> |
diff --git a/pages/test_analytics/importing_junit_xml.md b/pages/test_engine/importing_junit_xml.md
similarity index 81%
rename from pages/test_analytics/importing_junit_xml.md
rename to pages/test_engine/importing_junit_xml.md
index a300e03478..d29c05a03e 100644
--- a/pages/test_analytics/importing_junit_xml.md
+++ b/pages/test_engine/importing_junit_xml.md
@@ -1,6 +1,6 @@
# Importing JUnit XML
-While most test frameworks have a built-in JUnit XML export feature, these JUnit reports do not provide detailed span information. Therefore, features in Test Analytics that depend on span information aren't available when using JUnit as a data source. If you need span information, consider using the [JSON import](/docs/test-analytics/importing-json) API instead.
+While most test frameworks have a built-in JUnit XML export feature, these JUnit reports do not provide detailed span information. Therefore, features in Test Engine that depend on span information aren't available when using JUnit as a data source. If you need span information, consider using the [JSON import](/docs/test-engine/importing-json) API instead.
## Mandatory JUnit XML attributes
@@ -15,11 +15,11 @@ To learn more about the JUnit XML file format, see [Common JUnit XML format & ex
## How to import JUnit XML in Buildkite
-It's possible to import XML-formatted JUnit (or [JSON](/docs/test-analytics/importing-json#how-to-import-json-in-buildkite)) test results to Buildkite Test Analytics with or without the help of a plugin.
+It's possible to import XML-formatted JUnit (or [JSON](/docs/test-engine/importing-json#how-to-import-json-in-buildkite)) test results to Buildkite Test Engine with or without the help of a plugin.
### Using a plugin
-To import XML-formatted JUnit test results to Test Analytics using [Test Collector plugin](https://github.com/buildkite-plugins/test-collector-buildkite-plugin) from a build step:
+To import XML-formatted JUnit test results to Test Engine using [Test Collector plugin](https://github.com/buildkite-plugins/test-collector-buildkite-plugin) from a build step:
```yml
steps:
@@ -40,10 +40,10 @@ Using the plugin is the recommended way as it allows for a better debugging proc
If for some reason you cannot or do not want to use the [Test Collector plugin](https://github.com/buildkite-plugins/test-collector-buildkite-plugin), or if you are looking to implement your own integration, another approach is possible.
-To import XML-formatted JUnit test results to Test Analytics, make a `POST` request to `https://analytics-api.buildkite.com/v1/uploads` with a `multipart/form-data`.
+To import XML-formatted JUnit test results to Test Engine, make a `POST` request to `https://analytics-api.buildkite.com/v1/uploads` with a `multipart/form-data`.
For example, to import the contents of a `junit.xml` file in a Buildkite pipeline:
-1. Securely [set the Test Analytics token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
+1. Securely [set the Test Engine token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
1. Run the following `curl` command:
@@ -64,7 +64,7 @@ For example, to import the contents of a `junit.xml` file in a Buildkite pipelin
https://analytics-api.buildkite.com/v1/uploads
```
-To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-analytics/ci-environments#buildkite).
+To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-engine/ci-environments#buildkite).
Note that when a payload is processed, Buildkite validates and queues each test execution result in a loop. For that reason, it is possible for some to be queued and others to be skipped. Even when some or all test executions get skipped, REST API will respond with a `202 Accepted` because the upload and the run were created in the database, but the skipped test execution results were not ingested.
@@ -77,7 +77,7 @@ A single file can have a maximum of 5000 test results, and if that limit is exce
To import XML-formatted JUnit test results, make a `POST` request to `https://analytics-api.buildkite.com/v1/uploads` with a `multipart/form-data`.
For example, to import the contents of a `junit.xml` file in a CircleCI pipeline:
-1. Securely [set the Test Analytics token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
+1. Securely [set the Test Engine token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
1. Run the following `curl` command:
@@ -96,7 +96,7 @@ For example, to import the contents of a `junit.xml` file in a CircleCI pipeline
https://analytics-api.buildkite.com/v1/uploads
```
-To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-analytics/ci-environments#circleci).
+To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-engine/ci-environments#circleci).
Note that when a payload is processed, Buildkite validates and queues each test execution result in a loop. For that reason, it is possible for some to be queued and others to be skipped. Even when some or all test executions get skipped, REST API will respond with a `202 Accepted` because the upload and the run were created in the database, but the skipped test execution results were not ingested.
@@ -109,7 +109,7 @@ A single file can have a maximum of 5000 test results, and if that limit is exce
To import XML-formatted JUnit test results, make a `POST` request to `https://analytics-api.buildkite.com/v1/uploads` with a `multipart/form-data`.
For example, to import the contents of a `junit.xml` file in a GitHub Actions pipeline:
-1. Securely [set the Test Analytics token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
+1. Securely [set the Test Engine token environment variable](/docs/pipelines/security/secrets/managing) (`BUILDKITE_ANALYTICS_TOKEN`).
1. Run the following `curl` command:
@@ -129,7 +129,7 @@ For example, to import the contents of a `junit.xml` file in a GitHub Actions pi
https://analytics-api.buildkite.com/v1/uploads
```
-To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-analytics/ci-environments).
+To learn more about passing through environment variables to `run_env`-prefixed fields, see [CI environments](/docs/test-engine/ci-environments).
Note that when a payload is processed, Buildkite validates and queues each test execution result in a loop. For that reason, it is possible for some to be queued and others to be skipped. Even when some or all test executions get skipped, REST API will respond with a `202 Accepted` because the upload and the run were created in the database, but the skipped test execution results were not ingested.
diff --git a/pages/test_analytics/javascript_collectors.md b/pages/test_engine/javascript_collectors.md
similarity index 84%
rename from pages/test_analytics/javascript_collectors.md
rename to pages/test_engine/javascript_collectors.md
index 3b394eaca4..fd2c4ffd89 100644
--- a/pages/test_analytics/javascript_collectors.md
+++ b/pages/test_engine/javascript_collectors.md
@@ -1,6 +1,6 @@
# JavaScript collectors
-To use Test Analytics with your JavaScript (npm) projects, use the :github: [`test-collector-javascript`](https://github.com/buildkite/test-collector-javascript) package with a supported test framework. Test Analytics supports the following test frameworks:
+To use Test Engine with your JavaScript (npm) projects, use the :github: [`test-collector-javascript`](https://github.com/buildkite/test-collector-javascript) package with a supported test framework. Test Engine supports the following test frameworks:
- [Jest](https://jestjs.io/)
- [Jasmine](https://jasmine.github.io/)
@@ -8,7 +8,7 @@ To use Test Analytics with your JavaScript (npm) projects, use the :github: [`te
- [Cypress](https://www.cypress.io)
- [Playwright](https://playwright.dev)
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
## Add the test collector package
@@ -17,13 +17,13 @@ Whichever test framework you use, you first need to add and authenticate the [`b
To add the test collector package:
-1. In your CI environment, set the `BUILDKITE_ANALYTICS_TOKEN` environment variable to your Test Analytics API token.
+1. In your CI environment, set the `BUILDKITE_ANALYTICS_TOKEN` environment variable to your Test Engine API token.
To learn how to set environment variables securely in Pipelines, see [Managing pipeline secrets](/docs/pipelines/security/secrets/managing).
1. On the command line, create a new branch by running:
```
- git checkout -b install-buildkite-test-analytics
+ git checkout -b install-buildkite-test-engine
```
1. Install [`buildkite-test-collector`](https://www.npmjs.com/package/buildkite-test-collector) using your package manager.
@@ -46,11 +46,11 @@ With the test collector installed, you need to configure it in the test framewor
### Jest
-If you're already using Jest, you can add `buildkite-test-collector/jest/reporter` to the list of reporters to collect test results into your Test Analytics dashboard.
+If you're already using Jest, you can add `buildkite-test-collector/jest/reporter` to the list of reporters to collect test results into your Test Engine dashboard.
To configure Jest:
-1. Make sure Jest runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+1. Make sure Jest runs with access to [CI environment variables](/docs/test-engine/ci-environments).
1. Add `"buildkite-test-collector/jest/reporter"` to [Jest's `reporters` configuration array](https://jestjs.io/docs/configuration#reporters-arraymodulename--modulename-options) (typically found in `jest.config.js`, `jest.config.js`, or `package.json`):
```json
@@ -59,7 +59,7 @@ To configure Jest:
"testLocationInResults": true,
}
```
- **Note:** The `"testLocationInResults": true` setting enables column and line capture for Test Analytics.
+ **Note:** The `"testLocationInResults": true` setting enables column and line capture for Test Engine.
### Jasmine
@@ -127,13 +127,13 @@ To configure Mocha:
### Cypress
To configure Cypress:
-1. Make sure Cypress runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+1. Make sure Cypress runs with access to [CI environment variables](/docs/test-engine/ci-environments).
1. Update your [Cypress configuration](https://docs.cypress.io/guides/references/configuration).
```js
// cypress.config.js
- // Send results to Test Analytics
+ // Send results to Test Engine
reporter: "buildkite-test-collector/cypress/reporter",
```
@@ -142,7 +142,7 @@ To configure Cypress:
```js
// cypress.config.js
- // Send results to Test Analytics
+ // Send results to Test Engine
reporterOptions: {
token_name: "CUSTOM_ENV_VAR_NAME"
}
@@ -150,11 +150,11 @@ To configure Cypress:
### Playwright
-If you're already using Playwright, you can add `buildkite-test-collector/playwright/reporter` to the list of reporters to collect test results into your Test Analytics dashboard.
+If you're already using Playwright, you can add `buildkite-test-collector/playwright/reporter` to the list of reporters to collect test results into your Test Engine dashboard.
To configure Playwright:
-1. Make sure Playwright runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+1. Make sure Playwright runs with access to [CI environment variables](/docs/test-engine/ci-environments).
1. Add `"buildkite-test-collector/playwright/reporter"` to [Playwright's `reporter` configuration array](https://playwright.dev/docs/test-reporters#multiple-reporters) (typically found in `playwright.config.js`):
```js
@@ -180,7 +180,7 @@ When your collector is installed, commit and push your changes:
1. Commit the changes by running:
```shell
- git commit -m "Install and set up Buildkite Test Analytics"
+ git commit -m "Install and set up Buildkite Test Engine"
```
1. Push the changes by running:
@@ -191,13 +191,13 @@ When your collector is installed, commit and push your changes:
## View the results
-After completing these steps, you'll see the analytics of test executions on all branches that include this code in the Test Analytics dashboard.
+After completing these steps, you'll see the analytics of test executions on all branches that include this code in the Test Engine dashboard.
-If you don't see branch names, build numbers, or commit hashes in the Test Analytics dashboard, see [CI environments](/docs/test-analytics/ci-environments) to learn more about exporting your environment.
+If you don't see branch names, build numbers, or commit hashes in the Test Engine dashboard, see [CI environments](/docs/test-engine/ci-environments) to learn more about exporting your environment.
## Troubleshooting missing test executions and --forceExit
-Using the [`--forceExit`](https://jestjs.io/docs/cli#--forceexit) option when running Jest could result in missing test executions from Test Analytics.
+Using the [`--forceExit`](https://jestjs.io/docs/cli#--forceexit) option when running Jest could result in missing test executions from Test Engine.
`--forceExit` could potentially terminate any ongoing processes that are attempting to send test executions to Buildkite.
diff --git a/pages/test_engine/other_collectors.md b/pages/test_engine/other_collectors.md
new file mode 100644
index 0000000000..16c1ba20b4
--- /dev/null
+++ b/pages/test_engine/other_collectors.md
@@ -0,0 +1,7 @@
+---
+toc: false
+---
+
+# Collecting data from other test frameworks
+
+You can integrate any language and framework by uploading [Test Engine JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml) after your tests run. You can also [build your own collector](/docs/test-engine/your-own-collectors).
diff --git a/pages/test_analytics/permissions.md b/pages/test_engine/permissions.md
similarity index 78%
rename from pages/test_analytics/permissions.md
rename to pages/test_engine/permissions.md
index 96c348c569..9e46a9c4e0 100644
--- a/pages/test_analytics/permissions.md
+++ b/pages/test_engine/permissions.md
@@ -6,7 +6,7 @@ Enterprise customers can configure test suite permissions and security features
## Manage teams and permissions
-To manage teams across the Buildkite Test Analytics application, a _Buildkite organization administrator_ first needs to enable this feature across their organization. Learn more about how to do this in the [Manage teams and permissions section of Pipelines documentation](/docs/team-management/permissions#manage-teams-and-permissions).
+To manage teams across the Buildkite Test Engine application, a _Buildkite organization administrator_ first needs to enable this feature across their organization. Learn more about how to do this in the [Manage teams and permissions section of Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions).
Once the _teams_ feature is enabled, you can see the teams that you're a member of from the **User** page, which:
@@ -18,7 +18,7 @@ Once the _teams_ feature is enabled, you can see the teams that you're a member
### Organization-level permissions
-Learn more about what a _Buildkite organization administrator_ can do in the [Organization-level permissions section of the Pipelines documentation](/docs/team-management/permissions#manage-teams-and-permissions-organization-level-permissions).
+Learn more about what a _Buildkite organization administrator_ can do in the [Organization-level permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions-organization-level-permissions).
As an organization administrator, you can access the [**Organization Settings** page](https://buildkite.com/organizations/~/settings) by selecting **Settings** in the global navigation, where you can do the following:
@@ -26,15 +26,15 @@ As an organization administrator, you can access the [**Organization Settings**
<%= image "team-section-list.png", alt: "Screenshot of the Team section, showing a list of Teams" %>
-- After selecting a team, you can view and administer the member-, [pipeline-](/docs/team-management/permissions#manage-teams-and-permissions-pipeline-level-permissions), [test suite-](#manage-teams-and-permissions-test-suite-level-permissions), [registry-](/docs/packages/permissions#manage-teams-and-permissions-registry-level-permissions) and [team-](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions)level settings for that team.
+- After selecting a team, you can view and administer the member-, [pipeline-](/docs/pipelines/security/permissions#manage-teams-and-permissions-pipeline-level-permissions), [test suite-](#manage-teams-and-permissions-test-suite-level-permissions), [registry-](/docs/package-registries/security/permissions#manage-teams-and-permissions-registry-level-permissions) and [team-](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions)level settings for that team.
<%= image "team-section-test-suites-list.png", alt: "Screenshot of the Team section, showing a list of Test Suites the team has access to" %>
- **Note:** Registry-level settings are only available once [Buildkite Packages has been enabled](/docs/packages/permissions#enabling-buildkite-packages).
+ **Note:** Registry-level settings are only available once [Buildkite Package Registries has been enabled](/docs/package-registries/security/permissions#enabling-buildkite-packages).
### Team-level permissions
-Learn more about what _team members_ are and what _team maintainers_ can do in the [Team-level permissions section of the Pipelines documentation](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions).
+Learn more about what _team members_ are and what _team maintainers_ can do in the [Team-level permissions in the Platform documentation](/docs/team-management/permissions#manage-teams-and-permissions-team-level-permissions).
### Test suite-level permissions
@@ -70,7 +70,7 @@ These user-level permissions and security features are managed by _Buildkite org
1. Select **Settings** in the global navigation to access the [**Organization Settings**](https://buildkite.com/organizations/~/settings) page.
-1. Select [**Security** > **Test Analytics** tab](https://buildkite.com/organizations/~/security/test-analytics) to access your organization's security for Test Analytics page.
+1. Select [**Security** > **Test Engine** tab](https://buildkite.com/organizations/~/security/test-analytics) to access your organization's security for Test Engine page.
From this page, you can configure the following permissions for all users across your Buildkite organization:
diff --git a/pages/test_analytics/public_test_suites.md b/pages/test_engine/public_test_suites.md
similarity index 100%
rename from pages/test_analytics/public_test_suites.md
rename to pages/test_engine/public_test_suites.md
diff --git a/pages/test_analytics/python_collectors.md b/pages/test_engine/python_collectors.md
similarity index 65%
rename from pages/test_analytics/python_collectors.md
rename to pages/test_engine/python_collectors.md
index 0d16201413..48b741eb9c 100644
--- a/pages/test_analytics/python_collectors.md
+++ b/pages/test_engine/python_collectors.md
@@ -4,20 +4,20 @@ toc: false
# Python collectors
-To use Test Analytics with your Python projects use the [`buildkite-test-collector`](https://pypi.org/project/buildkite-test-collector/) package with pytest.
+To use Test Engine with your Python projects use the [`buildkite-test-collector`](https://pypi.org/project/buildkite-test-collector/) package with pytest.
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
## pytest collector
pytest is a testing framework for Python.
-If you're already using pytest, then you can install `buildkite-test-collector` to collect test results into your Test Analytics dashboard.
+If you're already using pytest, then you can install `buildkite-test-collector` to collect test results into your Test Engine dashboard.
-Before you start, make sure pytest runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+Before you start, make sure pytest runs with access to [CI environment variables](/docs/test-engine/ci-environments).
To get started with `buildkite-test-collector`:
-1. In your CI environment, set the `BUILDKITE_ANALYTICS_TOKEN` environment variable [securely](/docs/pipelines/security/secrets/managing) to your Buildkite Test Analytics API token.
+1. In your CI environment, set the `BUILDKITE_ANALYTICS_TOKEN` environment variable [securely](/docs/pipelines/security/secrets/managing) to your Buildkite Test Engine API token.
1. Add `buildkite-test-collector` to your list of dependencies. Some examples:
@@ -48,10 +48,10 @@ To get started with `buildkite-test-collector`:
```shell
$ git add .
- $ git commit -m "Install and set up Buildkite Test Analytics"
+ $ git commit -m "Install and set up Buildkite Test Engine"
$ git push
```
-Once you're done, in your Test Analytics dashboard, you'll see analytics of test executions on all branches that include this code.
+Once you're done, in your Test Engine dashboard, you'll see analytics of test executions on all branches that include this code.
-If you don't see branch names, build numbers, or commit hashes in Test Analytics, then read [CI environments](/docs/test-analytics/ci-environments) to learn more about exporting your environment to the collector.
+If you don't see branch names, build numbers, or commit hashes in Test Engine, then read [CI environments](/docs/test-engine/ci-environments) to learn more about exporting your environment to the collector.
diff --git a/pages/test_analytics/ruby_collectors.md b/pages/test_engine/ruby_collectors.md
similarity index 63%
rename from pages/test_analytics/ruby_collectors.md
rename to pages/test_engine/ruby_collectors.md
index dba2692bee..fea26b81d1 100644
--- a/pages/test_analytics/ruby_collectors.md
+++ b/pages/test_engine/ruby_collectors.md
@@ -1,21 +1,21 @@
# Ruby collectors
-To use Test Analytics with your [Ruby](https://www.ruby-lang.org/) projects use the :github: [`test-collectors-ruby`](https://github.com/buildkite/test-collector-ruby) gem with RSpec or minitest.
+To use Test Engine with your [Ruby](https://www.ruby-lang.org/) projects use the :github: [`test-collectors-ruby`](https://github.com/buildkite/test-collector-ruby) gem with RSpec or minitest.
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
## RSpec collector
[RSpec](https://rspec.info/) is a behavior-driven development library for Ruby.
-If you're already using RSpec for your tests, add the `buildkite-test_collector` gem to your code to collect your test results into your Test Analytics dashboard.
+If you're already using RSpec for your tests, add the `buildkite-test_collector` gem to your code to collect your test results into your Test Engine dashboard.
-Before you start, make sure RSpec runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+Before you start, make sure RSpec runs with access to [CI environment variables](/docs/test-engine/ci-environments).
1. Create a new branch:
```
- git checkout -b install-buildkite-test-analytics
+ git checkout -b install-buildkite-test-engine
```
2. Add `buildkite-test_collector` to your `Gemfile` in the `:test` group:
@@ -32,7 +32,7 @@ Before you start, make sure RSpec runs with access to [CI environment variables]
bundle
```
-3. Add the Test Analytics code to your application in `spec/spec_helper.rb`, and set the BUILDKITE_ANALYTICS_TOKEN [securely](/docs/pipelines/security/secrets/managing) on your agent or agents. Please ensure gems that patch `Net::HTTP`, like [httplog](https://github.com/trusche/httplog) and [sniffer](https://github.com/aderyabin/sniffer), are required before `buildkite/test_collector` to avoid conflicts.
+3. Add the Test Engine code to your application in `spec/spec_helper.rb`, and set the BUILDKITE_ANALYTICS_TOKEN [securely](/docs/pipelines/security/secrets/managing) on your agent or agents. Please ensure gems that patch `Net::HTTP`, like [httplog](https://github.com/trusche/httplog) and [sniffer](https://github.com/aderyabin/sniffer), are required before `buildkite/test_collector` to avoid conflicts.
```rb
require "buildkite/test_collector"
@@ -44,13 +44,13 @@ Before you start, make sure RSpec runs with access to [CI environment variables]
```sh
$ git add .
- $ git commit -m "Install and set up Buildkite Test Analytics"
+ $ git commit -m "Install and set up Buildkite Test Engine"
$ git push
```
-Once you're done, in your Test Analytics dashboard, you'll see analytics of test executions on all branches that include this code.
+Once you're done, in your Test Engine dashboard, you'll see analytics of test executions on all branches that include this code.
-If you don't see branch names, build numbers, or commit hashes in the Test Analytics UI, then see [CI environments](/docs/test-analytics/ci-environments) to learn more about exporting your environment to the collector.
+If you don't see branch names, build numbers, or commit hashes in the Test Engine UI, then see [CI environments](/docs/test-engine/ci-environments) to learn more about exporting your environment to the collector.
### Troubleshooting allow_any_instance_of errors
@@ -67,15 +67,15 @@ You can fix them by being more specific in your stubbing by replacing `allow_any
RSpec supports anonymous test casesβtests which are automatically named based on the subject and/or inputs to the expectations within the test. However, this can lead to unstable test names across different test runs, incorporating elements such as object IDs, database IDs, timestamps, and more.
-As a consequence, each test is assigned a new identity per run within Test Analytics. This poses a challenge for utilising the Test Analytics product effectively, as historical data across tests becomes difficult to track and analyze.
+As a consequence, each test is assigned a new identity per run within Test Engine. This poses a challenge for using the Test Engine product effectively, as historical data across tests becomes difficult to track and analyze.
-To mitigate this issue and ensure the reliability of Test Analytics, it's advisable to provide explicit and stable descriptions for each test case within your RSpec test suite. By doing so, you can maintain consistency in test identification across multiple runs, enabling better tracking and analysis of test performance over time.
+To mitigate this issue and ensure the reliability of Test Engine, it's advisable to provide explicit and stable descriptions for each test case within your RSpec test suite. By doing so, you can maintain consistency in test identification across multiple runs, enabling better tracking and analysis of test performance over time.
## minitest collector
[minitest](https://github.com/minitest/minitest) provides a complete suite of testing facilities supporting TDD, BDD, mocking, and benchmarking.
-If you're already using minitest for your tests, add the `buildkite-test_collector` gem to your code to collect your test results into your Test Analytics dashboard.
+If you're already using minitest for your tests, add the `buildkite-test_collector` gem to your code to collect your test results into your Test Engine dashboard.
1. Create a new branch:
@@ -97,7 +97,7 @@ If you're already using minitest for your tests, add the `buildkite-test_collect
bundle
```
-3. Add the Test Analytics code to your application in `test/test_helper.rb`, and set the BUILDKITE_ANALYTICS_TOKEN [securely](/docs/pipelines/security/secrets/managing) on your agent or agents. Please ensure gems that patch `Net::HTTP`, like [httplog](https://github.com/trusche/httplog) and [sniffer](https://github.com/aderyabin/sniffer), are required before `buildkite/test_collector` to avoid conflicts.
+3. Add the Test Engine code to your application in `test/test_helper.rb`, and set the BUILDKITE_ANALYTICS_TOKEN [securely](/docs/pipelines/security/secrets/managing) on your agent or agents. Please ensure gems that patch `Net::HTTP`, like [httplog](https://github.com/trusche/httplog) and [sniffer](https://github.com/aderyabin/sniffer), are required before `buildkite/test_collector` to avoid conflicts.
```rb
require "buildkite/test_collector"
@@ -109,13 +109,13 @@ If you're already using minitest for your tests, add the `buildkite-test_collect
```sh
git add .
- git commit -m "Install and set up Buildkite Test Analytics"
+ git commit -m "Install and set up Buildkite Test Engine"
git push
```
-Once you're done, in your Test Analytics dashboard, you'll see analytics of test executions on all branches that include this code.
+Once you're done, in your Test Engine dashboard, you'll see analytics of test executions on all branches that include this code.
-If you don't see branch names, build numbers, or commit hashes in the Test Analytics UI, then see [CI environments](/docs/test-analytics/ci-environments) to learn more about exporting your environment to the minitest collector.
+If you don't see branch names, build numbers, or commit hashes in the Test Engine UI, then see [CI environments](/docs/test-engine/ci-environments) to learn more about exporting your environment to the minitest collector.
## Adding annotation spans
diff --git a/pages/test_analytics/rust_collectors.md b/pages/test_engine/rust_collectors.md
similarity index 76%
rename from pages/test_analytics/rust_collectors.md
rename to pages/test_engine/rust_collectors.md
index 399267316f..7ba41b66d6 100644
--- a/pages/test_analytics/rust_collectors.md
+++ b/pages/test_engine/rust_collectors.md
@@ -4,13 +4,13 @@ toc: false
# Rust collector
-To use Test Analytics with your [Rust](https://www.rust-lang.org/) projects use the :github: [`test-collector-rust`](https://github.com/buildkite/test-collector-rust) package with `cargo test`.
+To use Test Engine with your [Rust](https://www.rust-lang.org/) projects use the :github: [`test-collector-rust`](https://github.com/buildkite/test-collector-rust) package with `cargo test`.
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
-Before you start, make sure Rust runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+Before you start, make sure Rust runs with access to [CI environment variables](/docs/test-engine/ci-environments).
-1. Create a [test suite](/docs/test-analytics/test-suites) and copy the API token that it gives you.
+1. Create a [test suite](/docs/test-engine/test-suites) and copy the API token that it gives you.
1. Install the `buildkite-test-collector` crate:
@@ -34,4 +34,4 @@ Before you start, make sure Rust runs with access to [CI environment variables](
$ cargo test -- -Z unstable-options --format json --report-time | buildkite-test-collector
```
-1. Confirm correct operation. Verify that the run is visible in the Buildkite analytics dashboard.
+1. Confirm correct operation. Verify that the run is visible in the Buildkite Test Engine dashboard.
diff --git a/pages/test_analytics/swift_collectors.md b/pages/test_engine/swift_collectors.md
similarity index 67%
rename from pages/test_analytics/swift_collectors.md
rename to pages/test_engine/swift_collectors.md
index 2515cd6122..8fac43b371 100644
--- a/pages/test_analytics/swift_collectors.md
+++ b/pages/test_engine/swift_collectors.md
@@ -4,17 +4,17 @@ toc: false
# Swift collectors
-To use Test Analytics with your Swift projects use the :github: [`test-collector-swift`](https://github.com/buildkite/test-collector-swift) package with XCTest.
+To use Test Engine with your Swift projects use the :github: [`test-collector-swift`](https://github.com/buildkite/test-collector-swift) package with XCTest.
-You can also upload test results by importing [JSON](/docs/test-analytics/importing-json) or [JUnit XML](/docs/test-analytics/importing-junit-xml).
+You can also upload test results by importing [JSON](/docs/test-engine/importing-json) or [JUnit XML](/docs/test-engine/importing-junit-xml).
## XCTest
[XCTest](https://developer.apple.com/documentation/xctest) is a test framework to write unit tests for your Xcode projects.
-Before you start, make sure XCTest runs with access to [CI environment variables](/docs/test-analytics/ci-environments).
+Before you start, make sure XCTest runs with access to [CI environment variables](/docs/test-engine/ci-environments).
-1. [Create a test suite](https://buildkite.com/docs/test-analytics) and copy the test suite API token.
+1. [Create a test suite](https://buildkite.com/docs/test-engine) and copy the test suite API token.
1. [Securely](/docs/pipelines/security/secrets/managing) set the `BUILDKITE_ANALYTICS_TOKEN` secret on your CI to the API token from the previous step.
@@ -49,14 +49,14 @@ Before you start, make sure XCTest runs with access to [CI environment variables
1. Commit and push your changes:
```bash
- git checkout -b add-buildkite-test-analytics
- git commit -am "Add Buildkite Test Analytics"
- git push origin add-buildkite-test-analytics
+ git checkout -b add-buildkite-test-engine
+ git commit -am "Add Buildkite Test Engine"
+ git push origin add-buildkite-test-engine
```
-Once you're done, in your Test Analytics dashboard, you'll see analytics of test executions on all branches that include this code.
+Once you're done, in your Test Engine dashboard, you'll see analytics of test executions on all branches that include this code.
-If you don't see branch names, build numbers, or commit hashes in Test Analytics, then read [CI environments](/docs/test-analytics/ci-environments) to learn more about exporting your environment to the collector.
+If you don't see branch names, build numbers, or commit hashes in Test Engine, then read [CI environments](/docs/test-engine/ci-environments) to learn more about exporting your environment to the collector.
### Debugging
diff --git a/pages/test_analytics/test_ownership.md b/pages/test_engine/test_ownership.md
similarity index 80%
rename from pages/test_analytics/test_ownership.md
rename to pages/test_engine/test_ownership.md
index e9c334b934..08070dc9e5 100644
--- a/pages/test_analytics/test_ownership.md
+++ b/pages/test_engine/test_ownership.md
@@ -1,10 +1,10 @@
# Test ownership
-Test ownership is critical in adopting a healthy testing culture at your organization. Defining one or more teams as test owners allows these teams to become accountable for maintaining a fast and reliable test suite, ensuring confidence when you deploy your code.
+Test ownership is critical in adopting a healthy testing culture at your organization. Defining one or more teams as test owners allows these teams to become accountable for maintaining tests within your test suite, ensuring it is fast and reliable, and providing confidence when you deploy your code.
-Customers on the [Pro and Enterprise plans](https://buildkite.com/pricing) can assign test ownership to [teams](/docs/test-analytics/permissions#manage-teams-and-permissions).
+Customers on the [Pro and Enterprise plans](https://buildkite.com/pricing) can assign test ownership to [teams](/docs/test-engine/permissions#manage-teams-and-permissions).
-Test ownership is managed via team assignments in a TESTOWNERS file. The team that is the default owner of a test [will be automatically assigned flaky tests](/docs/test-analytics/flaky-test-assignment) to triage.
+Test ownership is managed via team assignments in a TESTOWNERS file. The team that is the default owner of a test [will be automatically assigned flaky tests](/docs/test-engine/flaky-test-assignment) to triage.
> π§ Buildkite test ownership is currently in private beta
> Please reach out to our support team to register for early access.
@@ -19,8 +19,8 @@ A TESTOWNERS file uses Buildkite team slugs instead of user names. Your team slu
```bash
# Example team name to slug
Pipelines => pipelines
-Test Analytics => test-analytics
-π¦ Packages => packages
+Test Engine => test-engine
+π¦ Package Registries => package-registries
```
The following example TESTOWNERS file, which you can copy as a starting point, explains the syntax of this file and how it works:
@@ -49,8 +49,8 @@ The following example TESTOWNERS file, which you can copy as a starting point, e
* team-slug-1 team-slug-2
# In this example, any test file ending with `_spec.rb` will be
-# assigned to the `test-analytics` team and not `team-slug-1`.
-*_spec.rb test-analytics # This is an inline comment.
+# assigned to the `test-engine` team and not `team-slug-1`.
+*_spec.rb test-engine # This is an inline comment.
# In this example, the `pipelines` team owns all `.rb` test files.
*.rb pipelines
@@ -64,18 +64,18 @@ The following example TESTOWNERS file, which you can copy as a starting point, e
# like `spec/features/application_spec.rb`, but not any test files
# nested in any subdirectories of `spec/features`, such as
# `spec/features/pipelines/application_spec.rb`.
-spec/features/* test-analytics
+spec/features/* test-engine
# In this example, the `pipelines` team owns any test file in any
# `pipelines` directory, anywhere within the test location.
pipelines/ pipelines
-# In this example, the `test-analytics` team owns any test files
-# within an `/analytics` directory such as `/models/analytics`,
-# `/features/analytics`, and `/models/organizations/analytics`.
-# Any test files directly within the `/analytics` directory itself
-# will also belong to the `test-analytics` team.
-**/analytics test-analytics
+# In this example, the `test-engine` team owns any test files
+# within an `/test-engine` directory such as `/models/test-engine`,
+# `/features/test-engine`, and `/models/organizations/test-engine`.
+# Any test files directly within the `/test-engine` directory itself
+# will also belong to the `test-engine` team.
+**/test-engine test-engine
# In this example, the `pipelines` team owns any test files in the
# `/spec` directory at the root of the test location. However, the
@@ -88,7 +88,7 @@ pipelines/ pipelines
### Permission requirements
-The teams listed in your TESTOWNERS file must have [permission to access the test suite](/docs/test-analytics/permissions#manage-teams-and-permissions-test-suite-level-permissions) _before_ ownership records are created.
+The teams listed in your TESTOWNERS file must have [permission to access the test suite](/docs/test-engine/permissions#manage-teams-and-permissions-test-suite-level-permissions) _before_ ownership records are created.
## Setting test ownership
@@ -117,15 +117,15 @@ A TESTOWNERS file [follows the same rules as a `.gitignore` or `CODEOWNERS` file
```bash
# In a regular `.gitignore` or `CODEOWNER` file, the following
-# block would set the `test-analytics` team as the owner of any
+# block would set the `test-engine` team as the owner of any
# file in the `/specs` directory at the root of your test location
# except for the `/specs/features` subdirectory, as its owners are
# left empty.
# This functionality is not supported in a Buildkite `TESTOWNERS`
# file, where `/spec/features` would be also be owned by the
-# `test-analytics` team.
+# `test-engine` team.
-/specs/ test-analytics
+/specs/ test-engine
/specs/features
```
diff --git a/pages/test_engine/test_splitting.md b/pages/test_engine/test_splitting.md
new file mode 100644
index 0000000000..7a978243fe
--- /dev/null
+++ b/pages/test_engine/test_splitting.md
@@ -0,0 +1,16 @@
+---
+toc: false
+---
+
+# Test splitting
+
+Test splitting is a feature that:
+
+- Allows you to substantially reduce the duration of your overall build times, especially for pipelines with highly complex and computationally intensive test suites.
+- Intelligently partitions your test suites to run in parallel across multiple agents, with the intent to even out test execution times across your agents, such that each agent will complete its partitioned test executions at approximately similar times.
+
+The following image from Test Engine's test splitting setup page illustrates how this feature works. In this example, _without_ test splitting, the test suite build time would take as long as it takes for the slowest combination of tests to run on a single partition (Buildkite job), which is 10 minutes. Since the sum of all test executions across all agents is 16 minutes, _with_ test splitting implemented, all four partitions would take approximately 4 minutes to run, such that the overall test suite build time would be approximately 4 minutes, or a 6-minute reduction.
+
+<%= image "setup-page-summary.png", alt: "The test splitting setup page in Test Engine" %>
+
+Learn more about how to configure test splitting for your test suites in [Configuring test splitting](/docs/test-engine/test-splitting/configuring).
diff --git a/pages/test_engine/test_splitting/client_installation.md b/pages/test_engine/test_splitting/client_installation.md
new file mode 100644
index 0000000000..f929ce64d7
--- /dev/null
+++ b/pages/test_engine/test_splitting/client_installation.md
@@ -0,0 +1,69 @@
+# Installing the Test Engine Client
+
+This page provides instructions on how to install the Test Engine Client via installers provided by Buildkite.
+
+If you need to install this tool on a system without an installer listed below, you'll need to perform a manual installation using one of the binaries from [Test Engine Client's releases page](https://github.com/buildkite/test-engine-client/releases/latest). Once you have the binary, make it executable in your pipeline.
+
+## Debian
+
+1. Ensure you have curl and gpg installed first:
+
+ ```shell
+ apt update && apt install curl gpg -y
+ ```
+
+1. Install the registry signing key:
+
+ ```shell
+ curl -fsSL "https://packages.buildkite.com/buildkite/test-engine-client-deb/gpgkey" | gpg --dearmor -o /etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg
+ ```
+
+1. Configure the registry:
+
+ ```shell
+ echo -e "deb [signed-by=/etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/test-engine-client-deb/any/ any main\ndeb-src [signed-by=/etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/test-engine-client-deb/any/ any main" > /etc/apt/sources.list.d/buildkite-buildkite-test-engine-client-deb.list
+ ```
+
+1. Install the package:
+
+ ```shell
+ apt update && apt install bktec
+ ```
+
+## Red Hat
+
+1. Configure the registry:
+
+ ```shell
+ echo -e "[test-engine-client-rpm]\nname=Test Engine Client - rpm\nbaseurl=https://packages.buildkite.com/buildkite/test-engine-client-rpm/rpm_any/rpm_any/\$basearch\nenabled=1\nrepo_gpgcheck=1\ngpgcheck=0\ngpgkey=https://packages.buildkite.com/buildkite/test-engine-client-rpm/gpgkey\npriority=1" > /etc/yum.repos.d/test-engine-client-rpm.repo
+ ```
+
+2. Install the package:
+
+ ```shell
+ dnf install -y bktec
+ ```
+
+## macOS
+
+The Test Engine Client can be installed using [Homebrew](https://brew.sh) with [Buildkite tap formulae](https://github.com/buildkite/homebrew-buildkite). To install, run:
+
+```shell
+brew tap buildkite/buildkite && brew install buildkite/buildkite/bktec
+```
+
+## Docker
+
+You can run the Test Engine Client inside a Docker container using the official image in [Docker Hub](https://hub.docker.com/r/buildkite/test-engine-client/tags).
+
+To run the client using Docker:
+
+```shell
+docker run buildkite/test-engine-client
+```
+
+Or, to add the Test Engine Client binary to your Docker image, include the following in your Dockerfile:
+
+```dockerfile
+COPY --from=buildkite/test-engine-client /usr/local/bin/bktec /usr/local/bin/bktec
+```
diff --git a/pages/test_engine/test_splitting/configuring.md b/pages/test_engine/test_splitting/configuring.md
new file mode 100644
index 0000000000..3c5fdcd23d
--- /dev/null
+++ b/pages/test_engine/test_splitting/configuring.md
@@ -0,0 +1,172 @@
+# Configuring test splitting
+
+Buildkite maintains its open source Test Engine Client ([bktec](https://github.com/buildkite/test-engine-client)) tool. This tool uses your Test Engine test suite data to intelligently partition tests throughout your test suite into multiple sets, such that each set of tests runs in parallel across your agents. This results in a _test plan_, where a test plan defines which tests are run on which agents. Currently, the Test Engine Client tool only supports RSpec and Jest.
+
+## Dependencies
+
+The Test Engine Client relies on execution timing data captured by the test collectors from previous builds to partition your tests evenly across your agents. Therefore, you will need to configure the [Ruby test collector](/docs/test-engine/ruby-collectors) for your test suite if you are running RSpec, and [JavaScript test collector](/docs/test-engine/javascript-collectors) if you are running Jest.
+
+## Installation
+
+The Test Engine Client is supported on both Linux and macOS with 64-bit ARM and AMD architectures. You can install the client using the following installers:
+
+- [Debian](/docs/test-engine/test-splitting/client-installation#debian)
+- [Red Hat](/docs/test-engine/test-splitting/client-installation#red-hat)
+- [macOS](/docs/test-engine/test-splitting/client-installation#macos)
+- [Docker](/docs/test-engine/test-splitting/client-installation#docker)
+
+If you need to install this tool on a system without an installer listed above, you'll need to perform a manual installation using one of the binaries from [Test Engine Client's releases page](https://github.com/buildkite/test-engine-client/releases/latest). Once you have the binary, make it executable in your pipeline.
+
+## Using the Test Engine Client
+
+Once you have downloaded the Test Engine Client (bktec) binary and it is executable in your pipeline, you'll need to configure some additional environment variables for the Test Engine Client to function. You can then update your pipeline step to call `bktec` instead of calling RSpec to run your tests. Learn more about how to do this in [Update the pipeline step](#using-the-test-engine-client-update-the-pipeline-step).
+
+### Configure environment variables
+
+The Test Engine Client tool uses a number of [predefined](#predefined-environment-variables) and [mandatory](#mandatory-environment-variables) environment variables, as well as several optional ones for either [RSpec](#optional-rspec-environment-variables) or [Jest](#optional-jest-environment-variables).
+
+
+
+#### Predefined environment variables
+
+By default, the following predefined environment variables are available to your testing environment and do not need any further configuration. If, however, you use Docker or some other type of containerization tool to run your tests, and you wish to use these predefined environment variables in these tests, you may need to expose these environment variables to your containers.
+
+
+
+ <% TEST_SPLITTING_ENV['predefined'].each do |var| %>
+
+
+ <%= var['name'] %> #
+ |
+
+ <% var['desc'].each do |d| %>
+ <%= render_markdown(text: d) %>
+ <% end %>
+ |
+
+ <% end %>
+
+
+
+
+
+#### Mandatory environment variables
+
+The following mandatory environment variables must be set.
+
+
+
+ <% TEST_SPLITTING_ENV['mandatory'].each do |var| %>
+
+
+ <%= var['name'] %> #
+ |
+
+ <% var['desc'].each do |d| %>
+ <%= render_markdown(text: d) %>
+ <% end %>
+
+ <% if var['note'].present? %>
+
+ <% var['note'].each do |d| %>
+ <%= render_markdown(text: d) %>
+ <% end %>
+
+ <% end %>
+ |
+
+ <% end %>
+
+
+
+
+
+#### Optional RSpec environment variables
+
+The following optional RSpec environment variables can also be used to configure the Test Engine Client's behavior.
+
+
+
+ <% TEST_SPLITTING_ENV['optional']['rspec'].each do |var| %>
+
+
+ <%= var['name'] %> #
+
+ Default:
+ <%= var['default'] || "-" %>
+
+ |
+
+ <% var['desc'].each do |d| %>
+ <%= render_markdown(text: d) %>
+ <% end %>
+
+ <% if var['note'].present? %>
+
+ <% var['note'].each do |d| %>
+ <%= render_markdown(text: d) %>
+ <% end %>
+
+ <% end %>
+ |
+
+ <% end %>
+
+
+
+
+
+#### Optional Jest environment variables
+
+The following optional Jest environment variables can also be used to configure the Test Engine Client's behavior.
+
+
+
+ <% TEST_SPLITTING_ENV['optional']['jest'].each do |var| %>
+
+
+ <%= var['name'] %> #
+
+ Default:
+ <%= var['default'] || "-" %>
+
+ |
+
+ <% var['desc'].each do |d| %>
+ <%= render_markdown(text: d) %>
+ <% end %>
+
+ <% if var['note'].present? %>
+
+ <% var['note'].each do |d| %>
+ <%= render_markdown(text: d) %>
+ <% end %>
+
+ <% end %>
+ |
+
+ <% end %>
+
+
+
+
+### Update the pipeline step
+
+With the environment variables configured, you can now update your pipeline step to run the Test Engine Client instead of running RSpec, or Jest directly. The following example pipeline step demonstrates how to partition your RSpec test suite across 10 nodes.
+
+```
+steps:
+ - name: "RSpec"
+ command: bktec
+ parallelism: 10
+ env:
+ BUILDKITE_TEST_ENGINE_API_ACCESS_TOKEN: your-secret-token
+ BUILDKITE_TEST_ENGINE_RESULT_PATH: tmp/rspec-result.json
+ BUILDKITE_TEST_ENGINE_SUITE_SLUG: my-suite
+ BUILDKITE_TEST_ENGINE_RUNNER: rspec
+```
+{: codeblock-file="pipeline.yml"}
+
+## API rate limits
+
+There is a limit on the number of API requests that the Test Engine Client can make to the server. This limit is 10,000 requests per minute per Buildkite organization. When this limit is reached, the Test Engine Client will pause and wait until the next minute is reached before retrying the request. This rate limit is independent of the [REST API rate limits](/docs/apis/rest-api/limits), and only applies to the Test Engine Client's interactions with the Test Splitting API.
diff --git a/pages/test_analytics/test_suites.md b/pages/test_engine/test_suites.md
similarity index 54%
rename from pages/test_analytics/test_suites.md
rename to pages/test_engine/test_suites.md
index 3e46cefca5..aef1e61a2d 100644
--- a/pages/test_analytics/test_suites.md
+++ b/pages/test_engine/test_suites.md
@@ -1,18 +1,24 @@
# Configuring test suites
-In Test Analytics, a test _suite_ is a collection of tests. A suite has a _run_, which is the execution of tests in a suite. A suite's run is analogous to a pipeline's build.
+In Test Engine, a _test suite_ (or _suite_) is a collection of tests. A suite has a _run_, which is the execution of tests in a suite. A pipeline's build may create one or more of these runs.
Many organizations set up one suite per test framework, for example one suite for RSpec, and another suite for Jest. Others use a common standard, such as JUnit XML, to combine tests from multiple frameworks to set up custom backend and frontend suites.
-Each suite inside Test Analytics has a unique API token that you can use to route test information to the correct suite. Pipelines and test suites do not need to have a one-to-one relationship.
+Each suite inside Test Engine has a unique API token that you can use to route test information to the correct suite. Pipelines and test suites do not need to have a one-to-one relationship.
+
+To start configuring your test suite, you first need to have configured the appropriate _test collectors_ for your development project. Learn more about how to do this from the [Get started](/docs/test-engine#get-started) section of these docs.
To delete a suite, or regenerate its API token, go to suite settings.
## Parallelized builds
-Test Analytics works even when your test runs are split across different agents by de-duplicating against the Test Analytics API token and unique build identifier.
+In CI/CD, a build's tests can be made to run in parallel using features of your own CI/CD pipeline or workflow tool. Parallelized pipeline/workflow builds typically run and complete faster than builds which are not parallelized.
+
+In Buildkite Pipelines, you can run tests in parallel when they are configured as [parallel jobs](https://buildkite.com/docs/tutorials/parallel-builds#parallel-jobs).
-The information that serves as a unique build identifier differs between CI environments. For details, see `run_env[key]` environment variables on our [CI environments page](/docs/test-analytics/ci-environments).
+> π
+> When tests are run in parallel across multiple agents, they can be grouped into the same run by defining the same `run_env[key]` environment variable. Learn more about this environment variable and others in [CI environments](/docs/test-engine/ci-environments).
+> You can further speed up the duration of parallelized builds across multiple agents by implementing [test splitting](/docs/test-engine/test-splitting).
## Compare across branches
@@ -20,23 +26,23 @@ All test suites have a default branch so you can track trends for your most impo
Organizations typically choose their main production branch as their default, although this is not required.
-To change your default branch, go to suite settings. You can also filter Test Analytics views by any branch by typing its name into the branch query parameter in the Test Analytics URL.
+To change your default branch, go to suite settings. You can also filter Test Engine views by any branch by typing its name into the branch query parameter in the Test Engine URL.
## Detecting flaky tests
Flaky tests are automated tests that produce inconsistent or unreliable results, despite being run on the same code and environment. They cause frustration, decrease confidence in testing, and waste time while you investigate whether the failure is due to a genuine bug.
-Test Analytics detects flaky tests by surfacing when the same test is run multiple times on the same commit SHA with different results. The tests might run multiple times within a single build or across different builds. Either way, they are detected as flaky if they report both passed and failed results.
+Test Engine detects flaky tests by surfacing when the same test is run multiple times on the same commit SHA with different results. The tests might run multiple times within a single build or across different builds. Either way, they are detected as flaky if they report both passed and failed results.
-If your test suite supports it, we recommend enabling the option to retry failed tests automatically. Automatic retries are typically run more often and provide more data to detect flaky tests. If you can't use automatic retries, Test Analytics also detects flaky tests from manual retries.
+If your test suite supports it, we recommend enabling the option to retry failed tests automatically. Automatic retries are typically run more often and provide more data to detect flaky tests. If you can't use automatic retries, Test Engine also detects flaky tests from manual retries.
Alternatively, you can create [scheduled builds](/docs/pipelines/scheduled-builds) to run your test suite on the default branch. You can schedule them outside your typical development time to run the test suite multiple times against the same commit SHA. You can still enable test retries in this setup, but they're less important. The more builds you run, the more likely you'll detect flaky tests that fail infrequently.
-Test Analytics reviews the test results to detect flaky tests after every test run.
+Test Engine reviews the test results to detect flaky tests after every test run.
## Tracking reliability
-Test Analytics calculates reliability of both your entire test suite and individual tests as a measure of flakiness over time.
+Test Engine calculates reliability of both your entire test suite and individual tests as a measure of flakiness over time.
_Reliability_ is defined as percentage calculated by:
@@ -45,7 +51,7 @@ _Reliability_ is defined as percentage calculated by:
Other test execution results such as `unknown` and `skipped` are ignored in the test reliability calculation.
-In Test Analytics, a run is marked as `failed` as soon as a test execution fails, regardless of whether it passes on a retry. This helps surface unreliable tests. You can have a situation where a build eventually passes on retry in a Pipeline, and the related run is marked as `failed` in Test Analytics.
+In Test Engine, a run is marked as `failed` as soon as a test execution fails, regardless of whether it passes on a retry. This helps surface unreliable tests. You can have a situation where a build eventually passes on retry in a Pipeline, and the related run is marked as `failed` in Test Engine.
## Trends and analysis
@@ -59,6 +65,6 @@ Select any individual test execution to see more trend and deep-dive information
<%= image "test-execution-stats.png", width: 1170, height: 578, alt: "Screenshot of individual test execution page showing test information related to that individual execution of the test" %>
-You can also annotate span information to help investigate problems, and see detailed log information inside Test Analytics for any failed test or run.
+You can also annotate span information to help investigate problems, and see detailed log information inside Test Engine for any failed test or run.
<%= image "span-timeline.png", width: 1125, height: 451, alt: "Screenshot of span timeline with user-defined annotation" %>
diff --git a/pages/test_engine/usage_and_billing.md b/pages/test_engine/usage_and_billing.md
new file mode 100644
index 0000000000..c814a12229
--- /dev/null
+++ b/pages/test_engine/usage_and_billing.md
@@ -0,0 +1,43 @@
+# Usage and billing
+
+Test Engine is designed to optimize your test suites through the management of your tests.
+
+## Managed tests
+
+Each and every test that can be uniquely identified by its combination of test suite, scope, and name, is a _managed test_, which in turn is used for billing purposes in Test Engine.
+
+For example, each of the following three tests are unique managed tests:
+
+- Test Suite 1 - here.is.scope.one - Login Test name
+- Test Suite 1 - here.is.another.scope - Login Test name
+- Test Suite 2 - here.is.scope.one - Login Test name
+
+Test Engine conducts the following on each managed test:
+
+- Tracks its history
+- Calculates its [flakiness](/docs/test-engine/test-suites#detecting-flaky-tests)
+- Maintains its state (for example, [Enterprise plan](https://buildkite.com/pricing) customers can quarantine tests by disabling them under certain conditions)
+- Attributes [ownership by team](/docs/test-engine/test-ownership)
+
+For billing purposes, Buildkite measures usage by calculating the number of managed tests that have executed (run) at least once each day, and then bills based on the 90th percentile of this usage for the month. This billing method ensures that occasional spikes in usage, such as those caused by refactoring, don't result in excessive charges.
+
+> π
+> Be aware that if a specific managed test has run multiple times on a specific day, then this only counts once towards the usage measurement for that day.
+
+## Test executions
+
+Some legacy Buildkite plans measure usage based on the _total number of times_ a test was executed (run).
+
+You can find the test execution details for a run at the bottom of the run page, and your organization's [total usage](#usage-page) in Settings.
+
+<%= image "test_executions.png", alt: "Test executions run page" %>
+
+## Usage page
+
+The [Usage page](https://buildkite.com/organizations/~/usage?product=test_engine) is available on every Buildkite plan, and shows a breakdown of all billable usage for your organization including managed tests and test executions.
+
+The [managed tests usage page](https://buildkite.com/organizations/~/usage/test_engine_managed_tests) graphs the maximum number of unique tests per day over the organization's billing periods. This page includes a breakdown of usage by suite and a CSV download of usage over the period.
+
+The [test executions usage page](https://buildkite.com/organizations/~/usage/test_executions) graphs the total executions over the organization's billing periods. This page includes a breakdown of usage by suite and a CSV download of usage over the period.
+
+Your organization's usage is also accessible in the [GraphQL API](/docs/apis/graphql/cookbooks/organizations#query-the-usage-api).
diff --git a/pages/test_engine/your_own_collectors.md b/pages/test_engine/your_own_collectors.md
new file mode 100644
index 0000000000..9726ed2999
--- /dev/null
+++ b/pages/test_engine/your_own_collectors.md
@@ -0,0 +1,9 @@
+---
+toc: false
+---
+
+# Your own collectors
+
+Test Engine integrates directly with your test runner to provide in-depth information about your tests (including spans) in real time.
+
+If you're interested in building your own fully integrated Test Engine collector for specific test runners, have a look at our [example collector](https://github.com/buildkite/rspec-buildkite-analytics) on GitHub.
diff --git a/spec/features/emojicom_rendering_spec.rb b/spec/features/emojicom_rendering_spec.rb
index c5a1d69ca9..4148ec516d 100644
--- a/spec/features/emojicom_rendering_spec.rb
+++ b/spec/features/emojicom_rendering_spec.rb
@@ -11,7 +11,7 @@
context "landing page" do
scenario "does display emojicom widget" do
- visit "/docs/test-analytics"
+ visit "/docs/test-engine"
expect(page).to have_css "#emojicom-widget-inline"
end
diff --git a/spec/helpers/application_helper_spec.rb b/spec/helpers/application_helper_spec.rb
index f38e61baa6..6f1611e531 100644
--- a/spec/helpers/application_helper_spec.rb
+++ b/spec/helpers/application_helper_spec.rb
@@ -36,15 +36,15 @@
context "when the path contains dashes" do
it "replaces dashes with spaces" do
- path = "test-analytics/importing-junit-xml"
+ path = "test-engine/importing-junit-xml"
- expect(top_level_nav_item_name(path)).to eq("Test Analytics")
+ expect(top_level_nav_item_name(path)).to eq("Test Engine")
end
it "titleizes" do
- path = "test-analytics/importing-junit-xml"
+ path = "test-engine/importing-junit-xml"
- expect(top_level_nav_item_name(path)).to eq("Test Analytics")
+ expect(top_level_nav_item_name(path)).to eq("Test Engine")
end
end
end
diff --git a/spec/models/page/renderer_spec.rb b/spec/models/page/renderer_spec.rb
index 29b58fc49d..3192c91383 100644
--- a/spec/models/page/renderer_spec.rb
+++ b/spec/models/page/renderer_spec.rb
@@ -99,11 +99,11 @@
context "non-external links" do
it "does not affect /docs/ links" do
md = <<~MD
- [Test Analytics](/docs/test-analytics)
+ [Test Engine](/docs/test-engine)
MD
html = <<~HTML
- Test Analytics
+ Test Engine
HTML
expect(Page::Renderer.render(md).strip).to eql(html.strip)
@@ -111,7 +111,7 @@
it "does not affect links to Buildkite domains" do
md = <<~MD
- [Test Analytics](https://buildkite.com/test-analytics)
+ [Test Engine](https://buildkite.com/test-engine)
[GraphQL Explorer](https://graphql.buildkite.com/explorer)
@@ -119,7 +119,7 @@
MD
html = <<~HTML
- Test Analytics
+ Test Engine
GraphQL Explorer
diff --git a/spec/scripts/graphql_api_content/nav_data_spec.rb b/spec/scripts/graphql_api_content/nav_data_spec.rb
index 771ca40774..407f69684a 100644
--- a/spec/scripts/graphql_api_content/nav_data_spec.rb
+++ b/spec/scripts/graphql_api_content/nav_data_spec.rb
@@ -10,8 +10,8 @@
"path" => "pipelines"
},
{
- "name" => "Test Analytics",
- "path" => "test-analytics",
+ "name" => "Test Engine",
+ "path" => "test-engine",
},
{
"name" => "APIs",
diff --git a/vale/styles/Buildkite/h1-h6_sentence_case.yml b/vale/styles/Buildkite/h1-h6_sentence_case.yml
index 97eff668e4..8a7931b2fa 100644
--- a/vale/styles/Buildkite/h1-h6_sentence_case.yml
+++ b/vale/styles/Buildkite/h1-h6_sentence_case.yml
@@ -47,7 +47,7 @@ exceptions:
- Buildkite
- Buildkite Agent
- Buildkite Agents
- - Buildkite Packages
+ - Buildkite Package Registries
- Buildkite Pipelines
- buildkite-agent
- BuildNotify
@@ -110,6 +110,7 @@ exceptions:
- Installation
- JavaScript
- Jenkins
+ - Jest
- JSON
- JUnit
- KMS
@@ -147,7 +148,8 @@ exceptions:
- S3
- SSH
- SSO
- - Test Analytics
+ - Test Engine
+ - Test Engine Client
- TESTOWNER
- Ubuntu
- URL
diff --git a/vale/styles/vocab.txt b/vale/styles/vocab.txt
index 58544c5abf..2bf1f625b1 100644
--- a/vale/styles/vocab.txt
+++ b/vale/styles/vocab.txt
@@ -29,6 +29,7 @@ Basecamp
Basscss
Bazel
Bitium
+bktec
boolean
Boomper
Buildbox
@@ -90,6 +91,7 @@ githooks
GitLab
globbing
gotestsum
+gpg
Gradle
Graviton
gz