From 3ce3b3fb3a9d086394bdba1c7ce4a5d12023d05f Mon Sep 17 00:00:00 2001 From: jacobwgillespie <130874+jacobwgillespie@users.noreply.github.com> Date: Mon, 10 Aug 2026 08:39:14 +0000 Subject: [PATCH] Update docs content from https://github.com/depot/app --- content/ci/compatibility.mdx | 15 +- content/ci/how-to-guides/cache-disks.mdx | 130 ++---------- content/ci/how-to-guides/split-tests.mdx | 198 ++++++++++++++++++ content/ci/observability/depot-ci-logs.mdx | 2 +- .../observability/depot-ci-test-results.mdx | 13 +- content/ci/oidc.mdx | 4 +- content/ci/overview.mdx | 2 +- content/cli/reference/container-builds.mdx | 1 + content/cli/reference/depot-ci.mdx | 11 + content/cli/reference/overview.mdx | 100 +++++++++ content/code/overview.mdx | 143 +++++++++++++ content/code/quickstart.mdx | 76 +++++++ content/environment-variables.mdx | 12 +- .../github-actions-test-results.mdx | 13 +- content/github-actions/overview.mdx | 4 - content/github-actions/runner-types.mdx | 7 +- content/observability.mdx | 47 +++-- content/posthog-for-startups.mdx | 29 +++ content/registry/overview.mdx | 4 +- content/security.mdx | 2 +- 20 files changed, 636 insertions(+), 177 deletions(-) create mode 100644 content/ci/how-to-guides/split-tests.mdx create mode 100644 content/code/overview.mdx create mode 100644 content/code/quickstart.mdx create mode 100644 content/posthog-for-startups.mdx diff --git a/content/ci/compatibility.mdx b/content/ci/compatibility.mdx index 18c34ea..eb2a700 100644 --- a/content/ci/compatibility.mdx +++ b/content/ci/compatibility.mdx @@ -46,6 +46,14 @@ Depot CI executes GitHub Actions YAML workflows. The following tables list GitHu | `on.repository_dispatch` | Custom events sent through the GitHub API | ✅ | | `on.repository_dispatch.types` | Custom event type filters | ✅ | +### Native GitHub stacked pull requests + +Depot CI supports [native GitHub stacked pull requests](https://docs.github.com/en/pull-requests/tutorials/roll-out-stacked-prs) for `pull_request` workflows. Depot CI evaluates a stack's `branches` filter against its ultimate base branch, then runs the matching workflow for each pull request in the stack using that pull request's own merge ref. + +For pull requests in a stack, `github.event.pull_request.stack` exposes the stack's `number`, `size`, `position`, `base.ref`, and `base.sha`. The value is `null` for a pull request that is not in a stack. + +For ordinary pull requests without stack metadata, Depot CI continues to match `pull_request.branches` against the pull request's direct base branch. + ### Repository dispatch events `repository_dispatch` lets you trigger Depot CI workflows from outside GitHub by sending a custom event to the GitHub API — useful for kicking off a run from another system (for example, a deployment provider) without polling or running your own relay. @@ -157,7 +165,7 @@ Depot CI automatically reports GitHub checks for each job in a workflow run. For ### GitHub-only event triggers -The following events are GitHub-specific concepts that aren't applicable to Depot CI workflows, such as Issues, Discussions, and Pages. +The following events are GitHub-specific concepts that aren't applicable to Depot CI workflows, such as Discussions, Pages, and issue events other than comments. | **Field** | **Event type** | **Supported** | | -------------------------------- | ----------------------------- | ------------- | @@ -172,7 +180,6 @@ The following events are GitHub-specific concepts that aren't applicable to Depo | `on.fork` | GitHub specific event trigger | ❌ | | `on.gollum` | GitHub specific event trigger | ❌ | | `on.image_version` | GitHub specific event trigger | ❌ | -| `on.issue_comment` | GitHub specific event trigger | ❌ | | `on.issues` | GitHub specific event trigger | ❌ | | `on.label` | GitHub specific event trigger | ❌ | | `on.milestone` | GitHub specific event trigger | ❌ | @@ -199,7 +206,9 @@ Only Depot `runs-on` labels are supported. Nonstandard labels become `depot-ubun ### Permissions -The following permissions are supported: `actions`, `checks`, `contents`, `id-token`, `metadata`, `pull_requests`, `statuses`, `workflows`. +The following permissions are supported: `actions`, `checks`, `code-quality`, `contents`, `id-token`, `metadata`, `pull_requests`, `statuses`, `workflows`. + +The `code-quality` permission must be requested explicitly. It isn't included in `read-all` or `write-all`, which retain the existing permission set so older Depot Code Access GitHub App installations don't fail token creation before the new permission is approved. #### GitHub Packages authentication diff --git a/content/ci/how-to-guides/cache-disks.mdx b/content/ci/how-to-guides/cache-disks.mdx index e14b0d7..95c10c9 100644 --- a/content/ci/how-to-guides/cache-disks.mdx +++ b/content/ci/how-to-guides/cache-disks.mdx @@ -24,7 +24,7 @@ Each disk is identified by a name that is global to your Depot organization and read its contents, so don't store secrets or untrusted output on a cache disk. -An unlimited number of parallel workflows can read from the same disk at once. To coordinate writes from concurrent workflows, the action's `write-lock` input locks a directory for write operations so parallel writers don't corrupt shared state. If the locked directory doesn't exist yet, the action pre-creates it. +Multiple parallel workflows can mount, read from, and write to the same disk at once. The action mounts the disk in conditional mode, so writes don't require an explicit checkout step. Avoid having jobs modify the same files at the same time; use one writer with many readers or partition writes into separate directories. Public fork pull requests skip mounting the disk and only create the target directory, so untrusted forks can't read or write your organization's cached data. @@ -32,11 +32,11 @@ Public fork pull requests skip mounting the disk and only create the target dire A cache disk is a good fit when the work fits a shared directory: -- Package and build caches: Persist dependency and build caches between runs without the upload, download, and restore-key steps that `actions/cache` requires. The cache is just present on a real filesystem. See [caching package manager downloads](#example-cache-package-manager-downloads) for a complete example. +- Package and build caches: Persist dependency and build caches between runs without the upload, download, and restore-key steps that `actions/cache` requires. The cache is just present on a real filesystem. - Content-addressed tool caches: Point the mount at the tool's cache via env or flag: GOCACHE/GOMODCACHE, CARGO_HOME registry, ~/.m2, ~/.gradle, ccache/sccache, Bazel/buildkit local cache. - Sharing data between workflows: Write results to the disk in one workflow and consume them from another, or use files on the disk to communicate between jobs. -- Read-only reference data: Model weights, test fixtures, seed databases, toolchains/SDKs. Build once under a lock, read concurrently everywhere. -- Directory-partitioned writes: Matrix or monorepo jobs that each write-lock only their own slice (`/tmp/cache-mount/`, `/tmp/cache-mount/`) never contend. +- Read-only reference data: Model weights, test fixtures, seed databases, toolchains/SDKs. Populate once, then read concurrently everywhere. +- Directory-partitioned writes: Matrix or monorepo jobs that each write only their own slice (`/tmp/cache-mount/`, `/tmp/cache-mount/`) avoid contention. - Per-job downloads from S3: Anything you would otherwise download from S3 for each job. ## Mount a cache disk in a job @@ -55,7 +55,6 @@ jobs: with: name: my-org-build-cache path: /mnt/cache - write-lock: /mnt/cache - name: Build run: ./build.sh --cache-dir /mnt/cache @@ -63,127 +62,22 @@ jobs: The action takes the following inputs: -| Input | Required | Default | Description | -| ------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------- | -| `path` | Yes | — | The path to mount the cache disk at, for example `/mnt/cache`. | -| `name` | Yes | — | The name of the disk. Reuse the same name across runs to reference it. Created automatically on first use. | -| `write-lock` | No | — | Lock a directory for write operations. If the directory doesn't exist, it's pre-created. | -| `debug` | No | `false` | Enable verbose logging. | +| Input | Required | Default | Description | +| ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------- | +| `path` | Yes | — | The path to mount the cache disk at, for example `/mnt/cache`. | +| `name` | Yes | — | The name of the disk. Reuse the same name across runs to reference it. Created automatically on first use. | +| `debug` | No | `false` | Enable verbose logging. | ## Best practices - **Naming**: Because names are global and unique to the org, use a convention that prevents collisions and makes intentional sharing obvious, for example prefixing by repository or purpose. - **Sharing**: Reads are unlimited and concurrent, so a disk is well-suited to many-reader fan-out. Mount a shared name only where you mean to share. -- **Concurrent writes**: Use the `write-lock` input to lock a directory you write to so parallel writers don't corrupt shared state. +- **Concurrent writes**: Avoid having multiple jobs modify the same files at once. Prefer one writer with many readers, or give each writer a separate directory. - **Safety**: Don't store secrets or untrusted output. Any build in the organization that knows the disk name can read its contents. -## Understanding disk operations +## Concurrent access -### Read-only - -By default (when `write-lock` isn't used), the disks are in read-only mode. Technically a single client might perform certain write operations within already existing directories, but the write performance is lacking and we generally advise against it. As a rule of thumb, when `write-lock` isn't used, only use the disk for read operations. - -### Exclusive disk locking - -When `write-lock` is set to the `path`, the job exclusively locks the whole disk for writing. This means that other jobs are allowed to read the disk contents, but they will not be able to write to it. When there are multiple paths listed in `write-lock`, but one of them is the `path`, all the others are discarded, and **full lock** is acquired. - -#### Examples: - -**Locking the whole disk exclusively** -Other jobs may read, but not write its contents. - -```yaml -jobs: - mount-cache-disk: - runs-on: depot-ubuntu-latest - steps: - - uses: depot/cache-mount@v1 - with: - path: /tmp/cache-mount - name: my-disk - write-lock: | - /tmp/cache-mount -``` - -**Locking the whole disk exclusively & discarding other paths** -`/tmp/cache-mount/a` and `/tmp/cache-mount/b` locks are discarded, instead the whole disk is exclusively locked by job. - -```yaml -jobs: - mount-cache-disk: - runs-on: depot-ubuntu-latest - steps: - - uses: depot/cache-mount@v1 - with: - path: /tmp/cache-mount - name: my-disk - write-lock: | - /tmp/cache-mount/a - /tmp/cache-mount/b - /tmp/cache-mount -``` - -### Selective directory locking - -The cache disk doesn't support multi-write to the disk root, or within a directory, but allows multiple jobs writing into different directories at the same time. When multiple (non-overlapping) directories are listed in `write-lock`, the job acquires a lock only on them. Any other directory is lockable/writable by other jobs. We recommend locking certain directories instead of locking the whole disk. When the directory defined in `write-lock` doesn't exist, the action creates it. - -#### Example: - -`my-disk` has the following contents: - -```txt -/tmp/cache-mount/ - ├─ node_modules/ - ├─ public/ - ├─ src/ - ├─ .gitignore - ├─ package.json - ├─ README.md -``` - -The job is the following: - -```yaml -jobs: - mount-cache-disk: - runs-on: depot-ubuntu-latest - steps: - - uses: depot/cache-mount@v1 - with: - path: /tmp/cache-mount - name: my-disk - write-lock: | - /tmp/cache-mount/node_modules - /tmp/cache-mount/public -``` - -## Example: cache package manager downloads - -Point your package manager's cache directory at the mounted disk so dependencies are reused across runs. - -```yaml -jobs: - install: - runs-on: depot-ubuntu-latest - steps: - - uses: actions/checkout@v6 - - - name: Mount cache disk - uses: depot/cache-mount@v1 - with: - name: my-org-pnpm-store - path: /mnt/cache/pnpm - write-lock: /mnt/cache/pnpm - - - name: Install dependencies - run: | - pnpm config set store-dir /mnt/cache/pnpm - pnpm install -``` - -Because `pnpm install` writes to the store, the mount sets `write-lock` so the job can populate the cache. Without it the disk is read-only, and the install can't update the store. This disk is dedicated to the pnpm store, so locking the whole mount is fine; if you share one disk across tools, lock only the subdirectory each job writes to. - -The same pattern works for other ecosystems by mounting the disk at the tool's cache directory, for example `/home/runner/.cargo` for Cargo or `/home/runner/.gradle/caches` for Gradle. Use an absolute path: the action passes `path` straight to the mount without shell expansion, so a `~` isn't resolved to the home directory and would create a literal `~` directory instead. The action creates the mount path if it doesn't already exist. +Cache disks support concurrent reads and writes from multiple workflows. Concurrent access doesn't make overlapping application writes atomic. For predictable results, use a single writer with multiple readers, partition writes so each job owns a separate subdirectory, or use content-addressed caches whose entries are immutable. ## Manage and delete cache disks diff --git a/content/ci/how-to-guides/split-tests.mdx b/content/ci/how-to-guides/split-tests.mdx new file mode 100644 index 0000000..ee8d8f3 --- /dev/null +++ b/content/ci/how-to-guides/split-tests.mdx @@ -0,0 +1,198 @@ +--- +title: Split tests by timing +ogTitle: Split Depot CI tests with historical timing data +description: Split a test suite across matrix jobs with historical JUnit timing data, then run and report every shard. +--- + +import {NoteCallout} from '~/components/blog/NoteCallout' + +Cut the wall-clock time of a large test suite by splitting it across jobs into balanced shards based on historical timing data. + + + `depot tests split`, `depot tests run`, and `depot tests report` are supported only in Depot CI and Depot GitHub + Actions runner jobs. Depot CI authenticates automatically. For Depot GitHub Actions runners, grant the workflow + `id-token: write` permission, as shown below. + + +## How it works + +Sharding tests across parallel jobs can reduce a suite’s wall-clock time, but a shard with disproportionately slow tests becomes the bottleneck that determines when the suite finishes. Using historical timing data to distribute tests evenly across shards helps reduce the suite’s total run time. + +Depot splits your tests by how long they take. First you give Depot a list of candidates. A candidate is one thing your test command can run, such as a test file or a package name. You also tell Depot how many shards to split into. Depot gives each shard a different, non-overlapping subset of the candidates, and it uses the time each candidate took in past runs to balance how long the shards take to run. Each job runs its shard and uploads a JUnit XML report. Depot uses the times in those reports to balance the next run. + +If a suite has no past timing data, filename candidates fall back to file-size splitting, and other candidates use fallback weights. Each later run uses the times from previous runs, so the split gets more balanced over time. + +## Split, run, and report in a matrix job + +[`depot/tests-run-action`](https://github.com/depot/tests-run-action) wraps `depot tests run`: it selects the list assigned to the current shard, runs your command, and uploads the JUnit XML report it creates. + +This Depot CI example creates four matrix jobs. Every job uses the same package list; Depot assigns each one a different, timing-balanced subset. + +```yaml +jobs: + test: + runs-on: depot-ubuntu-24.04 + strategy: + fail-fast: false + matrix: + shard: [0, 1, 2, 3] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-go@v5 + with: + go-version-file: go.mod + - name: Install gotestsum + run: | + go install gotest.tools/gotestsum@latest + echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH" + - name: Run test shard + uses: depot/tests-run-action@v1 + with: + candidates-command: go list ./... + command: mkdir -p reports && xargs gotestsum --junitfile reports/junit.xml -- + report-path: reports/junit.xml +``` + +The action installs no test-runner integration of its own. Replace `go list` and `gotestsum` with the candidate discovery and command your test framework needs. + +In Depot CI, `DEPOT_MATRIX_JOB_INDEX` and `DEPOT_MATRIX_JOB_TOTAL` supply this matrix job's shard position. When shard inputs are omitted, the CLI uses those values. Non-matrix jobs receive `0` and `1`, so they remain unsplit. + +On Depot GitHub Actions runners, pass the shard inputs explicitly instead: + +```yaml +permissions: + contents: read + id-token: write + +# ...inside depot/tests-run-action@v1 with: +index: ${{ strategy.job-index }} +total: ${{ strategy.job-total }} +``` + +Explicit shard inputs override the corresponding Depot CI values. For a direct `depot tests run` call, `--total 1` runs the complete candidate list, even inside a matrix. + +In a multi-axis matrix, set `index` and `total` explicitly when tests should split on only one axis instead of the flattened matrix. The following example splits only on `shard`. + +## Choose a split scope in a multi-axis matrix + +Automatic Depot CI values describe the immediate strategy's flattened matrix. A `type` × `usage` × `shard` matrix has 16 jobs, so it produces a 16-way split rather than four independent four-way splits. + +When only the `shard` axis should split tests instead of the flattened 16-job matrix, pass its index and total explicitly. In this example, each `runtime` and `usage` combination receives its own four-way split: + +```yaml +strategy: + matrix: + runtime: [node-20, node-22] + usage: [unit, integration] + shard: [0, 1, 2, 3] + +steps: + - uses: depot/tests-run-action@v1 + with: + candidates-command: ./discover-tests ${{ matrix.runtime }} ${{ matrix.usage }} + # Override the flattened matrix values: split only by the shard axis. + index: ${{ matrix.shard }} + total: 4 + split-key: ${{ matrix.runtime }}-${{ matrix.usage }} + # ...command and report path +``` + +In reusable workflows, use explicit values whenever the intended split scope differs from the called job's immediate strategy. + +## Choose a candidate source + +A candidate is one runnable unit that your test command accepts. It must map to either a filename or classname emitted by your runner's JUnit report. The [Depot CI matrix example](#split-run-and-report-in-a-matrix-job) uses `go list ./...` to produce Go package names, which the JUnit report treats as classnames. When the effective shard total is greater than one, provide exactly one candidate source: a candidate list, file, or command. When the effective total is `1`, a candidate source is optional and `depot tests run` runs the command with empty standard input when none is provided. + +- `candidates-command` runs dynamic discovery in the Depot CLI. Use it for commands such as `go list ./...`; its standard output must contain only one candidate per line, while diagnostics belong on standard error. +- `candidates-file` reads an existing or shared newline-delimited list. Use it for a large list or one another step has already generated. +- `candidates` provides a small, fixed newline-delimited list directly in the workflow. + +## Choose a candidate identity + +`candidate-type` is optional in both the action and CLI. When it is omitted, Depot infers `filename` when every candidate looks like a recognized source or test-file path; otherwise, it infers `classname`. The inferred or explicit type must match the identity in the uploaded JUnit report that Depot uses to look up timings. + +| Value | Use it when candidates match | JUnit timing field | +| ----------- | ---------------------------- | ------------------ | +| `filename` | Test-file paths | `file` | +| `classname` | Package or class names | `classname` | + +For the following validated test runners, use the recommended candidate type. This is not an exhaustive list. + +| Runner | Recommended `candidate-type` | Candidate type inferred correctly? | +| --------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------- | +| Node test | None | Yes (`filename`) | +| Vitest | `classname` | No — file-looking candidates infer as `filename`, but report timings use `classname`. | +| Jest with `jest-junit` file field | None | Yes (`filename`) | +| Playwright JUnit | `classname` | No — file-looking candidates infer as `filename`, but report timings use `classname`. | +| pytest (`junit_family=xunit1`) | None | Yes (`filename`) | +| RSpec JUnit formatter | None | Yes (`filename`) | +| gotestsum | None | Yes (`classname`) | + +You can omit `candidate-type` when the candidate strings' apparent file or class identity matches the identity recorded by the test report. Set it explicitly when they differ—especially when a runner accepts file paths but writes those paths to the JUnit `classname` field. Vitest and Playwright are examples: pass `candidate-type: classname` so Depot identifies their timings correctly. + +## Choose timing granularity + +`timings-type` controls the granularity of the timing data Depot uses for each candidate. `filename` and `classname` use timings recorded for the whole candidate and must match the resolved `candidate-type`; `testname` uses individual JUnit test cases and is the only timing identity that can differ. + +| Candidate type | Candidate-level default | Test-level option | +| -------------- | ----------------------- | ----------------- | +| `filename` | `filename` (`file`) | `testname` | +| `classname` | `classname` | `testname` | + +Use the default when the JUnit report records a timing for each candidate. Set `timings-type: testname` when the report has individual test cases and you want Depot to calculate each candidate's duration from those tests. For example, the [direct Go/gotestsum commands](#run-the-cli-directly) pass package candidates but use `timings-type: testname` to calculate package durations from their individual test names. + +## Use keys for advanced workflows + +Basic matrices need neither `split-key` nor `report-key`: the split identity defaults to the job and action identity, and the report identity remains the action default. Use `split-key` only when distinct logical suites in one job would otherwise share split scope, such as when they have different candidate lists, timing identities, or granularity. Give every shard of one suite the same `split-key`. + +For example, when one job runs browser and API test suites, keep their timing assignments separate: + +```yaml +steps: + - name: Run browser tests + uses: depot/tests-run-action@v1 + with: + split-key: browser-tests + report-key: browser-tests + # ...browser candidates and command + + - name: Run API tests + uses: depot/tests-run-action@v1 + with: + split-key: api-tests + report-key: api-tests + # ...API candidates and command +``` + +`report-key` identifies a report upload. Use a distinct value only when one job uploads more than one report; ordinary matrix jobs need no per-shard `report-key`. + +## Run the CLI directly + +Use `depot tests split` when you only need Depot to print a shard's candidates: + +```shell +depot tests split \ + --candidates-command 'go list ./...' \ + --timings-type testname \ + --index 0 \ + --total 4 +``` + +Use `depot tests run` to select a shard, run a command, and upload its reports in one command: + +```shell +mkdir -p reports +depot tests run \ + --candidates-command 'go list ./...' \ + --timings-type testname \ + --index 0 \ + --total 4 \ + --command 'xargs gotestsum --junitfile reports/junit.xml --' \ + --report-path reports/junit.xml +``` + +You can also pass candidates through standard input or an existing list with `--candidates-file`. + +For either command, Depot uses historical timings when it has them. A first run still works: filename candidates fall back to file-size splitting, and other candidates use deterministic fallback weights. After a run uploads JUnit XML, those durations are available to balance later runs. + +See [Depot CI test results](/docs/ci/observability/depot-ci-test-results) or [GitHub Actions test results](/docs/github-actions/observability/github-actions-test-results) for JUnit reporting, result views, and analytics. diff --git a/content/ci/observability/depot-ci-logs.mdx b/content/ci/observability/depot-ci-logs.mdx index e710f60..ec4b2a7 100644 --- a/content/ci/observability/depot-ci-logs.mdx +++ b/content/ci/observability/depot-ci-logs.mdx @@ -27,7 +27,7 @@ Click a step name to collapse or expand its log output. Use **Expand all** in th ![Depot CI job logs](/images/docs/depot-ci-logviewer-expanded.png) -You can also fetch logs from the command line with [`depot ci logs`](/docs/cli/reference/depot-ci#depot-ci-logs), which streams the log output for a specific job attempt to stdout, or programmatically with the [Depot CI API](/docs/api/ci/reference). +You can also fetch logs from the command line with [`depot ci logs`](/docs/cli/reference/depot-ci#depot-ci-logs), which prints a job attempt's log output to stdout. Add `--follow` (or `-f`) to stream a running job's logs as they're produced, or pass `--follow` to [`depot ci run`](/docs/cli/reference/depot-ci#depot-ci-run) to start a run and follow its logs in one command. To read logs programmatically, use the [Depot CI API](/docs/api/ci/reference). ## Link to a job from within a workflow diff --git a/content/ci/observability/depot-ci-test-results.mdx b/content/ci/observability/depot-ci-test-results.mdx index cb84f4f..1e3f344 100644 --- a/content/ci/observability/depot-ci-test-results.mdx +++ b/content/ci/observability/depot-ci-test-results.mdx @@ -4,13 +4,6 @@ ogTitle: Depot CI test results and analytics in Depot description: Report JUnit XML test results from Depot CI jobs and view inline results, per-job history, and an org-wide analytics dashboard from the Depot dashboard. --- -import {NoteCallout} from '~/components/blog/NoteCallout' - - - Test results are in beta and free to use during the beta period. If you have suggestions to make this feature better, - [reach out](/help) and let us know. - - Depot CI can ingest JUnit XML test reports from your jobs and display them in the Depot dashboard. Add the `depot/test-report-action` to your workflow after your test step, pointed at your test runner's JUnit XML output. ## Report test results from a Depot CI job @@ -105,7 +98,7 @@ The job-level test results page (linked from the inline section above) lists eve Each failing row expands to show the failure message, failure type, stack trace, and captured `stdout` and `stderr`. -For sharded or matrix jobs, use **View group results** to see related shard jobs together for the selected attempt. The grouped view shows each shard's status, duration, result counts, and reported tests, with links back to the individual job result pages. +For sharded or matrix jobs, use **View group results** to see related shard jobs together for the selected attempt. The grouped view shows each shard's status, duration, result counts, and reported tests, with links back to the individual job result pages. To create those shards from the timing data in these reports, see [Split tests by timing](/docs/ci/how-to-guides/split-tests). The page includes the following historical context for each test: @@ -157,4 +150,6 @@ For the full list of flags and usage, see [`depot tests`](/docs/cli/reference/ov ## Pricing -Test results are free to use during the beta period. +The Developer and Startup plans each include 1,000,000 passing test results per month at no charge. Beyond that, it's $0.000001 per passing test, or $1 per 1 million tests. Failed, errored, and skipped tests are free. + +Test-results usage is billed monthly along with the rest of your Depot usage. Your organization's [usage page](/orgs/_/usage/) breaks down reports, total tests, and billable tests by day and by repository. If you're on the Business plan or an annual contract, [contact us](mailto:contact@depot.dev) for custom volume pricing. See [Pricing](/pricing) for full plan details. diff --git a/content/ci/oidc.mdx b/content/ci/oidc.mdx index 76881c5..de2a2dc 100644 --- a/content/ci/oidc.mdx +++ b/content/ci/oidc.mdx @@ -45,8 +45,8 @@ The following is an example token: "run_number": "42", "sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2", "sub": "spiffe://identity.depot.dev/org/org_xxxxxxxxxxxxxxxxxxxx/ci/github/my-org/my-repo/ref/refs/heads/main/sandbox/snd_xxxxxxxxxxxx", - "workflow": ".depot/workflows/ci.yaml", - "workflow_ref": "my-org/my-repo/.depot/workflows/ci.yaml@refs/heads/main", + "workflow": "ci.yaml", + "workflow_ref": "my-org/my-repo/ci.yaml@refs/heads/main", "workflow_sha": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" } ``` diff --git a/content/ci/overview.mdx b/content/ci/overview.mdx index 076192b..b4cfed4 100644 --- a/content/ci/overview.mdx +++ b/content/ci/overview.mdx @@ -35,7 +35,7 @@ Your original `.github/` workflows continue running on GitHub in parallel until
  • Runs your existing GitHub Actions YAML workflows.
    • -
  • Supports push, pull request, pull request review, deployment status, schedule, workflow dispatch, workflow call, workflow run, and merge group triggers.
    • +
  • Supports push, pull request, issue comment, pull request review, deployment status, schedule, workflow dispatch, workflow call, workflow run, and merge group triggers.
diff --git a/content/cli/reference/container-builds.mdx b/content/cli/reference/container-builds.mdx index 9cee3fd..8159d8d 100644 --- a/content/cli/reference/container-builds.mdx +++ b/content/cli/reference/container-builds.mdx @@ -403,6 +403,7 @@ Additional flags that can be used with this command. | `organization` | Depot organization ID | | `region` | Build data will be stored in the chosen region (default "us-east-1") | | `cache-storage-policy` | Build cache to keep per architecture in GB (default 50) | +| `cache-policy-keep-days` | Build cache retention in days (default 14; 0 means no limit) | | `token` | Depot token | {/* */} diff --git a/content/cli/reference/depot-ci.mdx b/content/cli/reference/depot-ci.mdx index 6035d1a..f4cb1f4 100644 --- a/content/cli/reference/depot-ci.mdx +++ b/content/cli/reference/depot-ci.mdx @@ -148,6 +148,7 @@ If you have local changes relative to your branch's remote state, the CLI automa | `--job ` | Job name to run; can be repeated to select multiple jobs. Omit to run all jobs. | | `--ssh` | Start the run and connect to the job's sandbox via interactive terminal. Requires exactly one `--job`. | | `--ssh-after-step ` | Insert an SSH debug session (via tmate) after the nth step (1-based). Requires exactly one `--job`. | +| `--follow`, `-f` | Stream the triggered run's logs once it starts. Cannot be combined with `--ssh` or `--ssh-after-step`. | | `--repo ` | GitHub repository to use instead of detecting from git remotes | | `--org ` | Organization ID (required when user is a member of multiple organizations) | | `--token ` | Depot API token | @@ -178,6 +179,16 @@ depot ci run --workflow .depot/workflows/ci.yml --job build --ssh-after-step 3 Both `--ssh` and `--ssh-after-step` require exactly one `--job` to be specified. The two flags are mutually exclusive: pass one or the other, not both. +### Follow live logs + +Use `--follow` (or `-f`) to stream the run's logs as soon as it starts, without a separate `depot ci logs` call: + +```bash +depot ci run --workflow .depot/workflows/ci.yml --job test --follow +``` + +When you request a single `--job`, the command follows that job's logs. Otherwise it selects the job automatically when the run has only one, or prompts you to pick when several are running. `--follow` cannot be combined with `--ssh` or `--ssh-after-step`. + ### What `depot ci run` does When you run `depot ci run` with local changes, the CLI automatically detects the changes and uploads a patch. For any job that has an `actions/checkout` step, the CLI injects a step into each job to apply that patch after checkout. The run reflects your local state without requiring a push. For branches that exist on the remote, the patch contains only unpushed changes. For local-only branches, the patch is relative to the default branch. diff --git a/content/cli/reference/overview.mdx b/content/cli/reference/overview.mdx index ed9b246..b752de6 100644 --- a/content/cli/reference/overview.mdx +++ b/content/cli/reference/overview.mdx @@ -98,6 +98,8 @@ $ depot org show List parsed test results for a Depot CI or GitHub Actions job. Results come from the JUnit XML your jobs report with the [`depot/test-report-action`](https://github.com/depot/test-report-action), the same data shown in the dashboard. To set up reporting, see [Depot CI test results](/docs/ci/observability/depot-ci-test-results) and [GitHub Actions test results](/docs/github-actions/observability/github-actions-test-results). +`depot tests split`, `depot tests run`, and `depot tests report` are supported only in Depot CI and Depot GitHub Actions runner jobs. Depot CI authenticates automatically. For Depot GitHub Actions runners, grant the workflow `id-token: write` permission. + By default, Depot uses the given ID to retrieve Depot CI results, then falls back to GitHub Actions. Pass `--ci` or `--gha` to restrict the lookup to one source. For Depot CI, the ID may be a run, job, or attempt ID. A job ID resolves to its latest attempt, and an attempt ID points at one specific attempt. A run ID resolves to the latest attempt when the run has a single job: if the run has more than one job, narrow it with `--job` (and `--workflow` when the same job name appears in multiple workflows). For GitHub Actions, pass the GitHub Actions job ID with `--gha`. The command prints a table in a terminal and JSON when piped, so it drops straight into scripts. @@ -142,3 +144,101 @@ $ depot tests --output json | `--output ` | Output format: `auto`, `table`, or `json` (default `auto`) | | `--org ` | Specify a Depot organization ID (required if you belong to more than one organization) | | `--token ` | Depot API token | + +### `depot tests split` + +Print the candidates assigned to one timing-balanced test shard. Use `--candidates-command` to discover runnable +candidates inline; standard input and `--candidates-file` remain supported alternatives. Use this lower-level command +when your test runner needs direct control over how it receives candidates. + +```shell +depot tests split \ + --candidates-command 'go list ./...' \ + --index 0 --total 4 \ + --timings-type testname +``` + +The command uses historical JUnit timings when available. Filename candidates without timing history fall back to file +size; other candidates receive deterministic fallback weights until Depot has timing data. See +[Split tests by timing](/docs/ci/how-to-guides/split-tests) for a complete workflow example. + +`--candidate-type` is optional. The CLI infers `filename` for recognized source or test-file paths and `classname` for +other candidates. Set it when that apparent identity differs from the JUnit field used for timing lookup; for example, +Vitest and Playwright accept file paths but write their timing identity to JUnit `classname`. + +`--timings-type` controls timing granularity. It defaults to the resolved candidate identity and uses whole-candidate +timings; set it to `testname` to calculate each candidate's duration from individual JUnit test cases rather than the +reported duration of the whole filename or classname unit. + +In Depot CI matrix jobs, omitted shard inputs use `DEPOT_MATRIX_JOB_INDEX` and `DEPOT_MATRIX_JOB_TOTAL`. Explicit flags +override those values. The automatic values cover the immediate strategy's flattened matrix; use explicit values when +only one matrix axis should split or when a reusable workflow needs a different split scope. + +**Flags** + +| Flag | Description | +| -------------------------------- | ----------------------------------------------------------------------- | +| `--index ` | Zero-based shard index; overrides the Depot CI matrix value. | +| `--total ` | Total number of shards; overrides the Depot CI matrix value. | +| `--candidate-type ` | Optional override for the runnable identity: `filename` or `classname`. | +| `--timings-type ` | Timing granularity: `filename`, `classname`, or `testname`. | +| `--candidates-command ` | Command that prints newline-delimited candidates. | +| `--candidates-file ` | File containing newline-delimited candidates instead of standard input. | +| `--key ` | Split-assignment key for distinct logical suites. | +| `--output ` | Candidate output format: `text` (default) or `json`. | + +### `depot tests run` + +Select a test shard, run a command with that shard's candidates on standard input, and upload the JUnit XML reports it +creates. The command preserves the test command's exit code, after attempting to upload reports even when tests fail. +In Depot CI matrix jobs, omitted shard inputs use `DEPOT_MATRIX_JOB_INDEX` and `DEPOT_MATRIX_JOB_TOTAL`. Explicit flags +override those values. Automatic values cover the immediate strategy's flattened matrix, so use explicit values when +only one axis should split or when a reusable workflow needs a different split scope. Set `--total 1` to run all +supplied candidates, even inside a matrix. Candidates are optional only when the effective total is `1`; then the +command runs with empty standard input if no candidate source is supplied. + +```shell +depot tests run \ + --candidates-command 'go list ./...' \ + --index 0 --total 4 \ + --timings-type testname \ + --command 'xargs gotestsum --junitfile reports/junit.xml --' \ + --report-path reports/junit.xml +``` + +Use `--split-key` only to separate logical test suites that would otherwise share a split scope. `--report-key` +identifies a report upload; use a distinct value only when one job uploads more than one report. For GitHub Actions and +Depot CI workflows, see the +[`depot/tests-run-action`](https://github.com/depot/tests-run-action) example in +[Split tests by timing](/docs/ci/how-to-guides/split-tests). + +`--timings-type` controls timing granularity. It defaults to the resolved candidate identity and uses whole-candidate +timings; set it to `testname` to calculate each candidate's duration from individual JUnit test cases rather than the +reported duration of the whole filename or classname unit. + +**Flags** + +| Flag | Description | +| -------------------------------- | ---------------------------------------------------------------------------------------------- | +| `--index ` | Zero-based shard index; overrides the Depot CI matrix value. | +| `--total ` | Total number of shards; overrides the Depot CI matrix value. `1` runs all supplied candidates. | +| `--candidate-type ` | Optional override for the runnable identity: `filename` or `classname`. | +| `--timings-type ` | Timing granularity: `filename`, `classname`, or `testname`. | +| `--candidates-command ` | Command that prints newline-delimited candidates. | +| `--candidates-file ` | File containing newline-delimited candidates instead of standard input. | +| `--split-key ` | Split-assignment key. Share it across shards of one logical test suite. | +| `--report-key ` | Report upload key; set it only for multiple uploads in one job. | +| `--command ` | Required shell command that receives selected candidates on standard input. | +| `--report-path ` | Required JUnit XML path, directory, or glob; repeatable. | + +### `depot tests report` + +Upload JUnit XML files that a test command has already created. This is the reporting-only counterpart to `depot tests +run`. + +```shell +depot tests report reports/junit.xml --key unit-tests +``` + +Pass report paths as positional arguments or with repeatable `--report-path`. Use `--key` to identify an upload +invocation when the same job reports multiple independent suites. diff --git a/content/code/overview.mdx b/content/code/overview.mdx new file mode 100644 index 0000000..f7c7ad6 --- /dev/null +++ b/content/code/overview.mdx @@ -0,0 +1,143 @@ +--- +title: Depot Code +ogTitle: Overview of Depot Code +description: Learn about Depot Code, Depot's source control hosting built on a diskless Git server backed by blob storage that mirrors your GitHub repos and plugs into Depot CI. +--- + +import {DocsCTA} from '~/components/blog/CTA' +import {FAQSection, FAQItem} from '~/components/blog/FAQ' +import {NoteCallout} from '~/components/blog/NoteCallout' + +{/* TODO: gated behind depot-code-private-beta until GA; revisit beta framing at GA. */} + + + Depot Code is in private beta. Functionality and capabilities could change, and documentation might be out of date. + [Request access](https://forms.gle/33jJc3uQFQqYhkKKA) to enable it for your organization. + + +Depot Code is Depot's source control hosting. It's entirely Git under the hood, but the Git server is built on top of blob storage rather than a persistent file server, which makes it more reliable and scalable under heavy read and write load. +Create a repository in Depot, push to it as your daily driver, and trigger [Depot CI](/docs/ci/overview) jobs without round-tripping to an external host. + +## Why use Depot Code? + +- **Reliable at scale**: Git objects are stored in blob storage and Git servers run as stateless, horizontally scalable workers instead of a persistent file server, which decouples storage from compute. +- **Fast with Depot CI**: when a Depot Code repository is [mirrored](#feature-summary), Depot CI serves clones and fetches from Depot's own infrastructure instead of round-tripping to GitHub, so jobs get your code faster. + +{/* TODO: verify the reliability/scale claims with engineering before GA. */} + +## Feature summary + + + + + + + + + {/* prettier-ignore */} + + + + + + + + + + + + + + + + + + {/* TODO: add rows as the beta matures (SDK, access control, self-hosting). */} + +
+ Diskless Git server + +
    +
  • Git packfiles and indexes are stored as objects in blob storage instead of on a persistent file server.
    • +
  • Refs and metadata live in a transactional store, so Git servers are stateless, horizontally scalable workers.
    • +
+
+ Standalone and mirror repositories + +
    +
  • Standalone: create a fresh repository in Depot and push your code directly.
    • +
  • Mirror: keep a synced copy of an upstream GitHub repository so clones and fetches are served by Depot.
    • +
+
+ Use a standard Git workflow + +
    +
  • Create repositories from the Depot dashboard, then clone, push, and fetch with regular git commands.
    • +
  • Authenticate over HTTPS with a Depot access token.
    • +
+
+ Built for Depot CI + +
    +
  • Trigger [Depot CI](/docs/ci/overview) workflows from your Depot Code repositories on every push. Jobs fetch code from Depot Code without a round-trip to GitHub.
    • +
+
+ +## How Depot Code works + +Instead of the default Git server, Depot Code uses a diskless Git server that stores all content in blob storage (S3) and is fully horizontally scalable. It requires no distributed consensus and is optimized for throughput, uptime, and scale. + +The traditional hosting model uses a hub-and-spoke design that welds storage and compute together: pushes route through a proxy that streams updates across replicas running a multi-phase commit, and repos end up pinned to machines. You can't scale read/write capacity independently of storage capacity, so you have to provision for peak. + +Depot Code inverts the primitive. Git packfiles and their indexes become objects in blob storage, refs and metadata live in a transactional store, and Git servers become stateless workers you can scale horizontally. + +{/* TODO: add an architecture diagram and read/write path once internals are public. */} + +## Running Depot CI workflows + +Depot Code repositories will initiate `push` triggers for Depot CI workflows defined in `.depot/workflows/`. Depot Code repositories currently do not initiate triggers of any other type. When you push to a Depot Code repository, Depot CI runs every workflow with an `on: push` trigger against the pushed commit. Each new commit included in a push starts its own set of runs. + +Additionally, Depot CI triggers are currently disabled by default for standalone repos. Many workflow scripts contain subtle dependencies on GitHub and require workarounds. Please reach out to opt-in to Depot CI triggers for standalone repos. + +## Pricing + +{/* TODO: confirm beta pricing (free during beta? quotas/overage at GA). */} + +Depot Code is free to use during the private beta. + + + + Request access to the Depot Code private beta → + + + +## FAQ + + + + + Depot Code is Depot's source control hosting: a diskless Git server backed by blob storage that scales horizontally, + mirrors your GitHub repositories, and plugs straight into Depot CI. It's entirely Git under the hood, so you clone, + push, and fetch with regular Git commands. + + + + Traditional Git hosts pair storage and compute on persistent file servers and route every push through a multi-phase + commit across replicas. Depot Code stores Git objects in blob storage and keeps refs and metadata in a transactional + store, so Git servers are stateless, horizontally scalable workers. + + + + No. You can create a mirror repository that keeps a synced copy of an upstream GitHub repository, so your Depot CI + workflows are served by Depot without round-tripping to GitHub.{' '} + {/* TODO: confirm mirror replication direction/cadence and push-back to upstream. */} + + +{/* TODO: add FAQ entries for self-hosting, access control, SDK. */} + + + +## Next steps + +- [Quickstart for Depot Code](/docs/code/quickstart) +- [Depot CI overview](/docs/ci/overview) diff --git a/content/code/quickstart.mdx b/content/code/quickstart.mdx new file mode 100644 index 0000000..23f7719 --- /dev/null +++ b/content/code/quickstart.mdx @@ -0,0 +1,76 @@ +--- +title: Quickstart for Depot Code +ogTitle: Getting started with Depot Code +description: Get started with Depot Code by creating a repository in the Depot dashboard, then cloning and pushing with plain Git. +--- + +import {NoteCallout} from '~/components/blog/NoteCallout' + +{/* TODO: gated behind depot-code-private-beta until GA; revisit beta framing at GA. */} + + + Depot Code is in private beta. Functionality and capabilities could change, and documentation might be out of date. + [Request access](https://forms.gle/33jJc3uQFQqYhkKKA) to enable it for your organization. + + +Create a Git repository hosted on Depot's diskless Git server, then clone, push, and fetch with regular `git` commands. Once your code is in Depot, you can trigger [Depot CI](/docs/ci/overview) workflows against it. + +## Prerequisites + +- A [Depot account](https://depot.dev/sign-up) with Depot Code enabled for your organization. +- [Git](https://git-scm.com/) installed locally. +- Optional: [Connect to GitHub](https://depot.dev/docs/ci/quickstart#connect-to-github) if you want to create a mirror repository in Depot Code. Check for an existing connection in your organization [**Settings**](/orgs/_/settings) under **GitHub Code Access**. + +## Create a repository + +Create a repository from the Depot dashboard. + +1. In the Depot dashboard, under **Code**, click **Repositories**. +2. Click **Create repository**. +3. Choose the repository type: + - **Standalone**: enter a repository name and a default branch name. Depot Code creates a fresh, empty repository for you to push your code to. + - **Mirror**: import a GitHub repository so Depot can serve clones and fetches. GitHub remains the source of truth because pushes through Depot are forwarded to GitHub. Upstream changes are imported when the mirror is refreshed. + +Repository names can include letters, numbers, dots, underscores, and hyphens, and can be namespaced with slashes, for example `team/service`. + +## Create an access token + +Depot Code authenticates Git over HTTPS using a Depot access token as the password, with `x-token` as the username. + +1. On the repository page in the Depot dashboard, click **Create access token**. +2. Copy the token immediately. For security, it's shown only once. + +{/* TODO: confirm where access tokens are managed and their scope (org vs repo). */} + +## Clone or push + +Copy the repository's clone URL from the dashboard. It has the form `https://.code.depot.dev/`, where your organization ID is the subdomain. + +Clone a repository: + +```bash +git clone https://x-token@.code.depot.dev/ +``` + +Or add Depot as a remote on an existing local repository and push: + +```bash +git remote add depot https://x-token@.code.depot.dev/ +git push -u depot main +``` + +The `x-token` username tells Git to prompt only for a password. Paste your [access token](#create-an-access-token) when prompted. To avoid re-entering it on every fetch and push, configure a [Git credential helper](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). + +Pushing to the Depot remote for a GitHub mirror repository also pushes those changes to GitHub. If you want Depot-only writes, create a standalone repository. + +To trial Depot Code alongside GitHub, keep GitHub as your `origin` remote and add Depot as a second remote. Run `git remote -v` to list the remotes configured for the repository. + +## Trigger Depot CI + +Depot Code repositories work with [Depot CI](/docs/ci/overview). To run CI, add a workflow file to `.depot/workflows/` in your repository, for example `.depot/workflows/ci.yml`, using GitHub Actions YAML syntax, then commit and push it. + +Depot Code workflows support the `push` trigger only. When you push, Depot CI runs every workflow with an `on: push` trigger against the pushed commit. + +Note: Depot CI triggers are currently disabled by default for standalone repos. Many workflow scripts contain subtle dependencies on GitHub and require workarounds. Please reach out to opt-in to Depot CI triggers for standalone repos. + +For workflow syntax and supported features, see the [Depot CI quickstart](/docs/ci/quickstart) and [compatibility reference](/docs/ci/compatibility). diff --git a/content/environment-variables.mdx b/content/environment-variables.mdx index b8c600d..a60ff6f 100644 --- a/content/environment-variables.mdx +++ b/content/environment-variables.mdx @@ -65,13 +65,17 @@ These variables are useful when configuring build tools to use Depot Cache. Some Depot CI jobs provide CI-specific variables, plus the authentication and identity variables listed in [Authentication and identity](#authentication-and-identity). -| Variable | Description | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `DEPOT_JOB_URL` | Direct link to the current Depot CI job attempt in the Depot dashboard. See [Link to a job from within a workflow](/docs/ci/observability/depot-ci-logs#link-to-a-job-from-within-a-workflow). | -| `GITHUB_ENVIRONMENT` | Workflow-derived environment name. Set when the job uses a static `environment:` value, such as `environment: production`. | +| Variable | Description | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `DEPOT_JOB_URL` | Direct link to the current Depot CI job attempt in the Depot dashboard. See [Link to a job from within a workflow](/docs/ci/observability/depot-ci-logs#link-to-a-job-from-within-a-workflow). | +| `DEPOT_MATRIX_JOB_INDEX` | Zero-based index of the job in its resolved strategy. `0` for jobs without a matrix. | +| `DEPOT_MATRIX_JOB_TOTAL` | Number of jobs in the resolved strategy. `1` for jobs without a matrix. | +| `GITHUB_ENVIRONMENT` | Workflow-derived environment name. Set when the job uses a static `environment:` value, such as `environment: production`. | Depot CI also supports GitHub Actions-compatible runtime variables and environment-file variables such as `GITHUB_ENV`, `GITHUB_OUTPUT`, `GITHUB_PATH`, `GITHUB_STATE`, and `GITHUB_STEP_SUMMARY` so existing GitHub Actions workflows and actions can pass environment variables, outputs, paths, state, and job summaries between steps. +`DEPOT_MATRIX_JOB_INDEX` and `DEPOT_MATRIX_JOB_TOTAL` mirror `strategy.job-index` and `strategy.job-total`. Composite actions inherit the calling job's values; jobs in reusable workflows use their own resolved strategy. + For full GitHub Actions compatibility details in Depot CI, see [Compatibility](/docs/ci/compatibility). ## Related reference diff --git a/content/github-actions/observability/github-actions-test-results.mdx b/content/github-actions/observability/github-actions-test-results.mdx index 697b094..9c81ed8 100644 --- a/content/github-actions/observability/github-actions-test-results.mdx +++ b/content/github-actions/observability/github-actions-test-results.mdx @@ -4,17 +4,12 @@ ogTitle: GitHub Actions test results and analytics in Depot description: Report JUnit XML test results from GitHub Actions jobs to Depot and view inline results per job plus an org-wide analytics dashboard from the Depot dashboard. --- -import {NoteCallout} from '~/components/blog/NoteCallout' - - - Test results are in beta and free to use during the beta period. If you have suggestions to make this feature better, - [reach out](/help) and let us know. - - Depot can ingest JUnit XML test reports from your GitHub Actions jobs and display them in the Depot dashboard. Add the `depot/test-report-action` to your workflow after your test step, pointed at your test runner's JUnit XML output. The action is supported on jobs using Depot GitHub Actions runners. Unsupported runner environments log a warning and skip upload. +Depot can also use the timing data in these reports to balance parallel test jobs. See [Split tests by timing](/docs/ci/how-to-guides/split-tests) for setup, including the GitHub Actions runner shard inputs. + ## Report test results from a GitHub Actions job Add the [`depot/test-report-action`](https://github.com/depot/test-report-action) action to your workflow after the step that runs your tests. Point it at the directory, file, or glob containing the JUnit XML output: @@ -150,4 +145,6 @@ For the full list of flags and usage, see [`depot tests`](/docs/cli/reference/ov ## Pricing -Test results are free to use during the beta period. +The Developer and Startup plans each include 1,000,000 passing test results per month at no charge. After that, it's $0.000001 per passing test, or $1 per 1 million tests. Failed, errored, and skipped tests are free. + +Test-results usage is billed monthly along with the rest of your Depot usage. Your organization's [usage page](/orgs/_/usage/) breaks down reports, total tests, and billable tests by day and by repository. If you're on the Business plan or an annual contract, [contact us](mailto:contact@depot.dev) for custom volume pricing. See [Pricing](/pricing) for full plan details. diff --git a/content/github-actions/overview.mdx b/content/github-actions/overview.mdx index a9848eb..a7b2d47 100644 --- a/content/github-actions/overview.mdx +++ b/content/github-actions/overview.mdx @@ -226,10 +226,6 @@ Larger runners consume your included GitHub Actions minutes faster (via multipli Included monthly minutes are not a hard cap. You can pay for additional GitHub Actions minutes on a per-minute basis. For per-minute pricing, see [GitHub Actions runner types](/docs/github-actions/runner-types). -### Estimate your cost savings - -To estimate the potential cost savings by switching to Depot GitHub Action runners, enter your current usage by runner type on our [GitHub Actions Price calculator](/github-actions-price-calculator). - ## FAQ diff --git a/content/github-actions/runner-types.mdx b/content/github-actions/runner-types.mdx index 4af15c4..798b2d9 100644 --- a/content/github-actions/runner-types.mdx +++ b/content/github-actions/runner-types.mdx @@ -113,8 +113,8 @@ The following labels are available: | Label | CPUs | Memory | Disk size | Disk accelerator size | Per-minute price | | :-------------------------------------- | :--- | :----- | :-------- | :-------------------- | :--------------- | -| `depot-macos-26` | 8 | 24 GB | 400 GB | 2 GB | $0.08 | -| `depot-macos-15` (`depot-macos-latest`) | 8 | 24 GB | 400 GB | 2 GB | $0.08 | +| `depot-macos-26` (`depot-macos-latest`) | 8 | 24 GB | 400 GB | 2 GB | $0.08 | +| `depot-macos-15` | 8 | 24 GB | 400 GB | 2 GB | $0.08 | | `depot-macos-14` | 8 | 24 GB | 400 GB | 2 GB | $0.08 | **Note:** due to licensing constraints from Apple, our macOS runner capacity is not fully elastic like our other runner types. We periodically update capacity to match demand, but macOS jobs can experience longer queue times during times of high demand. @@ -134,7 +134,8 @@ If you'd like to see what tools and software are installed in each runner image, - [`depot-ubuntu-24.04`](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md) and `depot-ubuntu-latest` - [`depot-ubuntu-22.04`](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md) -- [`depot-macos-15`](https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md) and `depot-macos-latest` +- [`depot-macos-26`](https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md) and `depot-macos-latest` +- [`depot-macos-15`](https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md) - [`depot-macos-14`](https://github.com/actions/runner-images/blob/main/images/macos/macos-14-Readme.md) - [`depot-windows-2025`](https://github.com/actions/runner-images/blob/main/images/windows/Windows2025-Readme.md) and `depot-windows-latest` - [`depot-windows-2022`](https://github.com/actions/runner-images/blob/main/images/windows/Windows2022-Readme.md) diff --git a/content/observability.mdx b/content/observability.mdx index 92b3d93..c4c160f 100644 --- a/content/observability.mdx +++ b/content/observability.mdx @@ -4,8 +4,6 @@ ogTitle: Overview of Depot observability description: View monthly usage metrics across all Depot services including billable minutes, storage, and resource consumption. --- -import {NoteCallout} from '~/components/blog/NoteCallout' - Metrics, logs, and analytics in the Depot dashboard. ## Organization-wide usage @@ -53,30 +51,35 @@ The GitHub Actions section shows summary metrics for all GitHub Actions jobs in Click on a day in the charts to filter all tables to show data for only that specific day. Use the filters to search for specific workflows, repositories, or runner types. -## Test results analytics by organization +## Test results usage by organization + +The Test Results section of the [organization usage page](/orgs/_/usage) shows how many test results Depot ingested for the selected month and how many of them are billable. Only passing tests are billable, so the billable count is lower than the total whenever a run has failing, errored, or skipped tests. For how this is priced, see [Depot CI test results](/docs/ci/observability/depot-ci-test-results#pricing) or [GitHub Actions test results](/docs/github-actions/observability/github-actions-test-results#pricing). - - Test results are in beta and free to use during the beta period. If you have suggestions to make this feature better, - [reach out](/help) and let us know. - +| Metric | Description | +| ------------------- | ----------------------------------------------------------- | +| Summary stats | Total reports, total tests, and total billable tests | +| Tests by source | Daily test counts split between Depot CI and GitHub Actions | +| Usage by repository | Reports, tests, and billable tests for each repository | + +## Test results analytics by organization The [Test Results Analytics page](/orgs/_/test-results/analytics) analyzes test results uploaded from your Depot CI jobs and GitHub Actions jobs, so you can see test health across the whole organization in one place. Results come from JUnit XML reports uploaded by the [`depot/test-report-action`](https://github.com/depot/test-report-action) action. For job-level setup, see [Depot CI test results](/docs/ci/observability/depot-ci-test-results) and [GitHub Actions test results](/docs/github-actions/observability/github-actions-test-results). -The dashboard summarizes the selected timeframe and breaks results down by source (Depot CI vs GitHub Actions), repository, branch, and test suite. Use the filter controls at the top of the page to narrow by timeframe, source (Depot CI or GitHub Actions), repository, branch, test suite, file, or class. Use linked failure cards and recent event rows to drill in to the originating run. - -| Metric | Description | -| --------------------------- | ------------------------------------------------------------------------------------------------------- | -| Overview | Total results, failure rate, error rate, P95 duration, and a Depot CI vs GitHub Actions split | -| Tests over time | Test count by status (passed, failed, errored, skipped) over the selected timeframe | -| Failure rate over time | Failure rate trend across the selected timeframe | -| Test duration distribution | Test counts bucketed by duration so you can see where time is being spent | -| Test duration trends | Per-suite P95 duration trend lines to spot slowdowns | -| Failure rates by suite | Suites ranked by failure rate so you can find the noisiest areas | -| Most frequent test failures | Tests ranked by failure count across the selected timeframe | -| New failures | Tests that started failing in the selected timeframe | -| Possibly flaky tests | Depot CI tests that had a failure on one attempt and then passed on a later attempt for the same SHA | -| Top 5 slowest tests | Individual tests ranked by P95 duration | -| Recent events | A reverse-chronological feed of failing test events with links back to the originating CI or GitHub job | +Every section on the page reflects the current timeframe and filters. The timeframe selector at the top right offers the past 7 days (the default), 30 days, 60 days, 90 days, or month to date. Below the header, filter by CI source (all, Depot CI, or GitHub Actions), repo, ref, suite, file, or class. Suite, file, and class cards link to a filtered view of the dashboard, and the external-link icons on failure cards and recent event rows drill into the originating Depot CI or GitHub Actions job. + +| Metric | Description | +| --------------------------- | ------------------------------------------------------------------------------------------------------------- | +| Overview | Total results, failure rate, error rate, P95 duration, and a Depot CI vs GitHub Actions split | +| Tests over time | Daily test volume with passed and failed results broken out | +| Failure rate over time | Daily failure and error rates as a share of total results | +| Failure rates by suite | Top 5 suites by combined failure and error rate | +| Most frequent test failures | Top 5 recurring failures by failure count, grouped by test and failure signature | +| New failures | Failures whose signature didn't appear in the 90 days before the timeframe, with the date each was first seen | +| Possibly flaky tests | Tests that both passed and failed across reruns of the same commit SHA, ranked by rerun count | +| Recent events | The 10 most recent failed or errored test events, newest first, with links back to the originating job | +| Test duration distribution | Timed test results bucketed by duration, from under 1 second to over 5 minutes | +| Top 5 slowest tests | Individual tests ranked by P95 duration | +| Test duration trends | Daily P95 duration lines for the 10 slowest suites in the timeframe | ## Storage diff --git a/content/posthog-for-startups.mdx b/content/posthog-for-startups.mdx new file mode 100644 index 0000000..16eed47 --- /dev/null +++ b/content/posthog-for-startups.mdx @@ -0,0 +1,29 @@ +--- +title: PostHog for Startups credits +ogTitle: Redeem your PostHog for Startups Depot credits +description: How to redeem the $5,000 Depot credit from PostHog for Startups, what it covers, and how long it lasts. +--- + +Depot is a partner in [PostHog for Startups](https://posthog.com/startups). Approved startups receive a partner code worth $5,000 in Depot credits. The offer is available to new Depot customers only. + +## How to redeem the code + +1. [Sign up](/sign-up) for a Depot account. +2. Go to your organization [Settings](/orgs/_/settings) page, or click **Configure billing** in the banner at the top of the Depot dashboard. +3. Select a plan. +4. Enter the partner code in the Stripe checkout window. + +Stripe checkout shows 100% off the first month and doesn't mention the $5,000. This is expected. Depot grants the credits automatically once you complete checkout. + +## How the credits work + +- The credits cover your plan (Developer or Startup) and all Depot usage, including container builds, GitHub Actions runners, Depot CI, Depot Registry, and Depot Cache. +- Each invoice draws from the credit balance until it's empty. There are no monthly limits. +- The credits are valid for one year, starting the day you activate the offer at checkout. +- Once the balance is exhausted, Depot charges plan fees and usage overages to the card on file. + + + +## Additional support + +If you have questions about your credits that aren't answered here, [reach out to support](/help). diff --git a/content/registry/overview.mdx b/content/registry/overview.mdx index dc3e260..a5ae5c8 100644 --- a/content/registry/overview.mdx +++ b/content/registry/overview.mdx @@ -80,7 +80,9 @@ docker login {orgId}.registry.depot.dev -u x-token -p ## Pricing -Depot Registry is included in all plans. Storage is billed at **$0.20/GB/month**. There are no charges for data transfer into or out of the registry. +Depot Registry is included in all plans. Registry storage counts toward the same included storage amount as your container build cache and [Depot Cache](/docs/cache/overview), which is 25 GB on Developer and 250 GB on Startup. Storage above the included amount is billed at **$0.20/GB/month**. There are no charges for data transfer into or out of the registry. + +See the [pricing page](/pricing) for plan details. ## Image retention diff --git a/content/security.mdx b/content/security.mdx index 833c539..64a9f28 100644 --- a/content/security.mdx +++ b/content/security.mdx @@ -25,7 +25,7 @@ Connections from the Depot CLI to the builder VM are routed through a stateless ### Physical Security -Our services and applications run in the cloud using one of our infrastructure providers, AWS and GCP. Depot has no physical access to the underlying physical infrastructure. For more information, see [AWS's security details](https://aws.amazon.com/security/) and [GCP's security details](https://cloud.google.com/docs/security/infrastructure/design). +Our services and applications run in the cloud using AWS. Depot has no physical access to the underlying physical infrastructure. For more information, see [AWS's security details](https://aws.amazon.com/security/). ### Data Encryption