flagon-io/g1t

public

1	---
2	title: GitHub Actions
3	description: Your GitHub Actions workflows run on g1t as they are. Rename .github to .g1t and push.
4	---
5
6	g1t runs GitHub Actions workflows. They are written exactly as on GitHub,
7	and kept in `.g1t/workflows/` instead of `.github/workflows/`.
8
9	## Moving from GitHub
10
11	```sh
12	git mv .github .g1t
13	git commit -m "Run our workflows on g1t"
14	git push g1t main
15	```
16
17	That is the whole move. Everything in the folder comes along: workflows,
18	local actions under `.g1t/actions/` and anything else you keep there.
19	Workflows that still say `uses: ./.github/actions/setup` find it under
20	`.g1t/` once `.github` is gone.
21
22	Otherwise g1t doesn't read `.github`, so a repository that lives in both
23	places can keep `.github` for GitHub and `.g1t` for g1t, side by side.
24
25	### On a mirror
26
27	A [mirror](/guides/mirroring/) of a GitHub repository runs nothing while it
28	stands by: its workflows run on GitHub. Its owners can change that:
29
30	- CI failover runs its workflows on g1t for each push copied in from
31	GitHub, `.github/workflows` as well as `.g1t/workflows`. Use it when
32	GitHub's workflows aren't running.
33	- Taking over runs them for everything pushed to g1t, until it's handed
34	back.
35	- Keep CI warm runs `.g1t/workflows`, and only those, on each push
36	copied in while it stands by.
37
38	When both folders have a workflow of the same `name:`, the one in `.g1t`
39	runs. A workflow that deploys (any job names an `environment:`) waits for
40	approval during CI failover and takeovers, so it doesn't deploy from two
41	places, unless the mirror's settings say otherwise. A push copied in from
42	GitHub that changes workflows or local actions waits for approval before
43	it can use the repository's secrets.
44
45	Then add your [secrets and variables](#secrets-and-variables): GitHub never
46	gives their values out, so they cannot be copied across.
47
48	## What runs
49
50	\| On GitHub \| On g1t \|
51	\| --- \| --- \|
52	\| `on:` `push` (branches, tags, paths), `pull_request`, `pull_request_target`, `issues`, `issue_comment`, `pull_request_review`, `schedule`, `workflow_dispatch`, `workflow_run`, `merge_group`, `create`, `repository_dispatch`, `release`, `deployment`, `deployment_status` \| The same, from g1t's own pushes, pull requests, issues, comments, [releases](#releases), [deployments](#deployments) and [merge queue](/guides/merge-queue/). `create` starts on each new branch or tag; `repository_dispatch` on [a dispatch event](#repository-dispatch). \|
53	\| `jobs`, `needs`, `if`, `outputs`, `env`, `defaults`, `timeout-minutes`, `continue-on-error` \| The same. \|
54	\| `timeout-minutes` and `continue-on-error` on a step \| The same, for `run:` and `uses:` steps alike. A `uses:` step's action is stopped at its limit, with every process it started; a step inside a composite action stops at its own limit or the `uses:` step's, whichever comes first. A step stopped this way fails, unless `continue-on-error` lets the job go on. \|
55	\| `strategy.matrix` with `include` and `exclude`, `fail-fast`, `max-parallel`, a matrix from `fromJSON(needs.…)` \| The same. \|
56	\| `concurrency` with `cancel-in-progress`, for the workflow or for one job \| The same: one run, or one job, of a group at a time. \|
57	\| `permissions:` for the workflow or for one job, `read-all`, `write-all` \| The same: they decide what [the job's token](#the-jobs-token) may do. \|
58	\| `${{ }}` expressions: every operator, function and context \| The same, including `hashFiles`, `success()`, `failure()`, `always()` and `cancelled()`. \|
59	\| `run:` with `bash`, `sh`, `python` or a custom shell \| The same. \|
60	\| JavaScript actions (`uses: owner/repo@v7`, `owner/repo/path@v7`) \| Fetched from that repository on g1t when g1t has it and your repository may use it, otherwise from GitHub, and run as they are, on Node 24, the runtime current actions declare. See [actions and workflows from other repositories](#actions-and-workflows-from-other-repositories). \|
61	\| Composite actions \| The same. \|
62	\| Reusable workflows (`jobs.<id>.uses: ./.g1t/workflows/build.yml`, or `owner/repo/.g1t/workflows/build.yml@v1` in another repository) \| The same: `with:` inputs, `secrets:` by name or `secrets: inherit`, `on.workflow_call` outputs, and nesting up to four deep. `.github/workflows/…` finds the workflow under `.g1t/` after the move. See [actions and workflows from other repositories](#actions-and-workflows-from-other-repositories). \|
63	\| `actions/checkout` \| Checks out from g1t, with `ref`, `fetch-depth`, `path`, `repository`, `token` and `submodules`. \|
64	\| `GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_PATH`, `GITHUB_STATE`, `GITHUB_STEP_SUMMARY` \| The same. Step summaries show on the run's page; see [job summaries](#job-summaries). \|
65	\| `::error::`, `::warning::`, `::notice::`, `::group::`, `::add-mask::` \| The same: errors and warnings become annotations on the run, and [masked](#masking-secrets) values stay hidden. \|
66	\| `secrets.`, `vars.`, `secrets.GITHUB_TOKEN` \| The same. `secrets.G1T_TOKEN` is [the job's own token](#the-jobs-token); `GITHUB_TOKEN` is its alias. \|
67	\| `environment:` on a job \| The job waits for the environment's [protection rules](#environments), then reads each key's row for that environment, as environment secrets work, and the run records a [deployment](/guides/deployments-api/#deployments-from-g1t-actions) to it. `url` gives the deployment its address; `deployment: false` reads the environment's values without making one. The name may be an expression. \|
68	\| `actions/upload-artifact`, `actions/download-artifact`, `actions/upload-artifact/merge` \| The same inputs and outputs as version 4: `retention-days`, `overwrite`, `compression-level`, `include-hidden-files`, `!` exclusions, download by `pattern` with `merge-multiple`, and from another run with `run-id` and `github-token`. Up to 5 GiB each; see [artifacts](#artifacts). \|
69	\| `actions/cache`, `actions/cache/restore`, `actions/cache/save` \| Kept per repository and branch, found by `key` or the newest under a `restore-keys` prefix. `path` takes globs and `!` exclusions. Up to 2 GiB each; see [the cache](#the-cache). \|
70	\| Actions that cache through the toolkit, such as `actions/setup-node` with `cache: npm` or `Swatinem/rust-cache` \| The same: they save to and restore from the repository's cache. See [actions built on the toolkit](#actions-built-on-the-toolkit). \|
71	\| sccache with `SCCACHE_GHA_ENABLED` \| The same: its entries go to the repository's cache. See [caching Rust builds](#caching-rust-builds). \|
72	\| `permissions: id-token: write` \| The job can ask for an OIDC token, and trade it for a cloud provider's credentials. See [OIDC tokens](#oidc-tokens). \|
73	\| `docker build`, `push`, `run`, `login`, `compose`, Buildx \| The same, with a Docker Engine of the job's own. See [Docker](#docker). \|
74	\| `services:` \| The same: each service starts before the steps, health checks are waited for, and it is reached at `localhost` on its port and by its name. \|
75	\| `container:` \| The same: every step runs inside the image. \|
76	\| `uses: docker://image`, Docker actions (`runs.using: docker`) \| The same: built from the action's Dockerfile or pulled, and run with GitHub's `/github/workspace` layout. \|
77	\| `docker/setup-buildx-action`, `docker/build-push-action`, `docker/login-action` \| The same. `setup-buildx-action` picks the job's own Engine as the builder. \|
78
79	The Actions page of a workflow says, under How this runs on g1t,
80	anything in it that runs differently.
81
82	### Not yet
83
84	- Windows and macOS on g1t's machines. g1t's own runners are Linux; a
85	job with `runs-on: windows-latest` or `macos-latest` fails, and says so.
86	[Self-hosted runners](/guides/self-hosted-runners/) of any OS run them:
87	`runs-on: [self-hosted, windows]`.
88	- Docker's `type=gha` build cache. Buildx skips it on g1t, and the
89	build runs without a cache. Use a registry cache instead; see
90	[caching image builds](#caching-image-builds).
91	- **Actions that upload artifacts with the toolkit's artifact library
92	themselves.** The library refuses to run against any server but
93	github.com. `actions/upload-artifact`, `actions/download-artifact` and
94	`actions/upload-artifact/merge` work, because g1t runs them itself. See
95	[actions built on the toolkit](#actions-built-on-the-toolkit).
96	- `on: delete`. Deleting a branch or tag starts no workflows yet; the
97	workflow's page says so.
98
99	Why each of these is missing, and what to use instead, is on
100	[What g1t can't do yet](/about/limitations/#actions-and-runners).
101
102	## Schedules
103
104	A workflow with `on: schedule` runs on the default branch's latest commit,
105	at each time its cron lines name, in UTC:
106
107	```yaml
108	on:
109	schedule:
110	- cron: "0 9 * * mon" # Mondays at 09:00 UTC
111	- cron: "/30 * * *" # every 30 minutes
112	```
113
114	Each line has five fields: minute, hour, day of month, month and day of
115	the week. A field takes `*`, a number, a range `1-5`, a list `1,15` and a
116	step `*/10`; days take `mon` to `sun`, and months `jan` to `dec`.
117
118	\| Rule \| What happens \|
119	\| --- \| --- \|
120	\| Every 5 minutes at most \| A schedule more frequent than every 5 minutes, such as `* * * * ` or `/2 * * * `, runs every 5 minutes instead, on the five-minute marks (:00, :05, :10 and so on), at each mark that ends five minutes in which it would have run. A mark outside the hours, days or months the schedule names never runs: ` 9 * * *` runs from 09:00 to 09:55. \|
121	\| No push for 60 days \| Schedules pause in a repository that has had no push for 60 days. The next push to any branch resumes them. Other events and `workflow_dispatch` still start the workflow. \|
122	\| Actions not paid for \| When a scheduled run's job could not start because the workspace's plan, spend limit or the open-source pool does not cover it, that run fails and says why, and the workflow's schedule waits an hour before it tries again. \|
123	\| Archived repository \| Schedules wait until the repository is unarchived. \|
124
125	## Actions and workflows from other repositories
126
127	A step's `uses: owner/repo@ref` (or `owner/repo/path@ref`) and a job's
128	`uses: owner/repo/.g1t/workflows/build.yml@ref` name another repository.
129	g1t looks for it on g1t first:
130
131	\| The repository \| What happens \|
132	\| --- \| --- \|
133	\| On g1t and public \| Your workflows use it, from any workspace. \|
134	\| On g1t, private, in your workspace, with Access set to Accessible from repositories in the workspace \| Your private repositories' workflows use it. A job reads it with a read-only token for that repository alone, which ends with the job. \|
135	\| On g1t, private, and not shared that way \| The step or job fails, and says why. A private repository's actions are never used by a public repository's workflows, whose logs anyone can read, nor from another workspace. \|
136	\| Not on g1t, or private in a workspace you cannot see \| An action is fetched from GitHub, as before; a reusable workflow is read from a public repository on GitHub. \|
137
138	`ref` is a branch, a tag or a commit. A reusable workflow may be under
139	`.g1t/workflows/` or `.github/workflows/`; a `.github/workflows/` path
140	also finds the file under `.g1t/workflows/` in a repository moved to
141	g1t. A `./.g1t/workflows/…` call inside a workflow from another
142	repository reads from that repository, at the same ref.
143
144	To share a private repository's actions and workflows with the rest of its
145	workspace, an admin chooses **Settings → Actions → Access → Accessible from
146	repositories in** the workspace, or calls
147	`PUT /repos/{owner}/{repo}/actions/permissions/access` with
148	`{"access_level": "organization"}` (`none` to stop).
149
150	### g1t's own actions
151
152	The `g1t` workspace on g1t.sh holds g1t's own actions, public, with a
153	`v1` tag that moves with each compatible release:
154
155	\| Action \| What it does \|
156	\| --- \| --- \|
157	\| [`g1t/deploy@v1`](https://g1t.sh/g1t/deploy) \| Builds the checkout and puts it on [g1t.page](/guides/deployments/): production from the project's production branch, a preview from a pull request or another branch. The job needs `deployments: write`. See [deploying from a workflow](/guides/deployments/#deploying-from-a-workflow). \|
158	\| [`g1t/detect@v1`](https://g1t.sh/g1t/detect) \| Says what that build would find (`kind`, `install`, `build`, `output-dir`) without building anything. \|
159
160	Both are composite actions around `g1t-runner`, which g1t's machines
161	have; on a [self-hosted runner](/guides/self-hosted-runners/) they use
162	the one on `PATH` or download the newest release.
163
164	### Secrets for a called workflow
165
166	A called workflow gets only the secrets its caller passes, plus
167	`G1T_TOKEN` (`GITHUB_TOKEN`):
168
169	```yaml
170	jobs:
171	build:
172	uses: acme/shared/.g1t/workflows/build.yml@v2
173	with:
174	node-version: 24
175	secrets:
176	npm-token: ${{ secrets.NPM_TOKEN }}
177
178	deploy:
179	uses: ./.g1t/workflows/deploy.yml
180	secrets: inherit
181	```
182
183	- `secrets:` with names passes each as the called workflow names it,
184	read from the caller's `secrets`, `needs`, `inputs`, `matrix`,
185	`github` and `vars`.
186	- `secrets: inherit` passes every secret the caller has.
187	- A job in the called workflow with its own `environment:` also reads that
188	environment's secrets, over what was passed.
189	- A secret the called workflow marks `required: true` under
190	`on.workflow_call.secrets` that the caller does not pass fails the
191	calling job before anything runs.
192
193	`vars` are the calling repository's, and a called workflow's jobs run
194	with the calling run's `github` context: `actions/checkout` checks out the
195	calling repository.
196
197	## Releases
198
199	Workflows with `on: release` start when a release changes, at the commit
200	its tag names (`GITHUB_REF` is `refs/tags/<tag>`). Each change is one or
201	more activity types, which `types:` chooses among:
202
203	\| Change \| Activity types \|
204	\| --- \| --- \|
205	\| A draft made \| `created` \|
206	\| A release made and published \| `created`, `published`, and `released` (or `prereleased` for a prerelease) \|
207	\| A draft published \| `published`, and `released` or `prereleased` \|
208	\| A prerelease made a full release \| `edited` and `released` \|
209	\| Made a draft again \| `unpublished` \|
210	\| Title, notes or prerelease changed \| `edited`, with `github.event.changes` holding the old title and notes \|
211	\| Deleted (the tag stays) \| `deleted` \|
212
213	```yaml
214	on:
215	release:
216	types: [published]
217	```
218
219	`github.event.release` has `tag_name`, `name`, `body`, `draft`,
220	`prerelease`, `target_commitish`, `author` and `html_url`. A release a
221	job's own token makes or changes starts no workflows.
222
223	## Deployments
224
225	`on: deployment` starts when a deployment is made, and
226	`on: deployment_status` when one has a new status: one reported through
227	the [deployments API](/guides/deployments-api/) or a
228	[g1t.page](/guides/deployments/) build. The run is at the commit deployed;
229	`GITHUB_REF` is the branch or tag deployed, and empty for a bare commit.
230
231	```yaml
232	on: deployment_status
233
234	jobs:
235	smoke:
236	if: github.event.deployment_status.state == 'success'
237	runs-on: ubuntu-latest
238	steps:
239	- run: curl -fsS "${{ github.event.deployment_status.environment_url }}"
240	```
241
242	`github.event.deployment` has `environment`, `ref`, `sha`, `task` and
243	`payload`; `github.event.deployment_status` has `state`, `environment_url`
244	and `log_url`. Deployments a workflow makes, with `environment:` or with
245	its job's token, start no workflows, so a workflow cannot set itself off.
246
247	## The runner
248
249	Jobs run in a fresh sandbox each: Debian with Node 24, Python 3, Go, Rust,
250	Java 21, .NET 8, Ruby 3.3, `build-essential`, `git`, `curl`, `jq`, Docker
251	(with Buildx and Compose) and passwordless `sudo`, in GitHub's layout
252	(`/home/runner/work`, `RUNNER_TEMP`, `RUNNER_TOOL_CACHE`).
253	`runner.os` is `Linux`. `ubuntu-latest`, `ubuntu-24.04` and other Linux
254	labels all run here. A job whose `runs-on` names `self-hosted` waits for one
255	of your [self-hosted runners](/guides/self-hosted-runners/) instead. Setup actions such as
256	`actions/setup-node` and `actions/setup-python` install other versions as
257	they do on GitHub.
258
259	### Languages and their setup actions
260
261	Each language below is on `PATH` from the job's first step, so a workflow
262	that only runs `java`, `dotnet` or `ruby` needs no setup step. When it has
263	one, the setup action finds the version that is already there and
264	downloads nothing.
265
266	\| Language \| Version \| Where \| Setup action \|
267	\| --- \| --- \| --- \| --- \|
268	\| Java \| Eclipse Temurin 21 (LTS), JDK \| `JAVA_HOME` (also `JAVA_HOME_21_X64`), in `RUNNER_TOOL_CACHE` \| `actions/setup-java` with `distribution: temurin` and `java-version: 21` uses it. Other versions and distributions are downloaded. \|
269	\| .NET \| SDK 8 (LTS) \| `DOTNET_ROOT`, `/usr/share/dotnet` \| `actions/setup-dotnet` with `dotnet-version: 8.0.x` keeps it when it is the newest 8.0 SDK, and installs other SDKs beside it. \|
270	\| Ruby \| 3.3, with Bundler \| in `RUNNER_TOOL_CACHE` \| `ruby/setup-ruby` with `ruby-version: '3.3'` (or a `.ruby-version` naming 3.3) uses it. \|
271	\| Node \| 24 \| `/usr/local/bin` \| `actions/setup-node` installs other versions. \|
272	\| Python \| 3.11 \| `/usr/bin/python3` \| `actions/setup-python` installs other versions. \|
273	\| Go \| 1.27 \| `/usr/local/go` \| `actions/setup-go` installs other versions. \|
274	\| Rust \| stable, with `rustfmt`, `clippy` and the `wasm32-unknown-unknown` target \| `~/.cargo/bin` \| `rustup` is there to add toolchains and targets. \|
275
276	```yaml
277	steps:
278	- uses: actions/checkout@v5
279	- uses: actions/setup-java@v5
280	with:
281	distribution: temurin
282	java-version: 21
283	- run: ./gradlew build
284	```
285
286	Because the sandbox runs Debian, `ruby/setup-ruby` treats it as a
287	self-hosted runner and uses only the Rubies in `RUNNER_TOOL_CACHE`. A version other than 3.3 fails at that step; install
288	it in a `run` step instead (for example with `ruby-build`) or run the job
289	in a `container:` with the Ruby you need, such as `ruby:3.4`.
290
291	The headers that gems and .NET need to build native code (`libyaml`,
292	`libffi`, `zlib`, OpenSSL, ICU) are installed too.
293
294	### Calling g1t's API from a job
295
296	The `gh` command is not installed: it needs a GraphQL API, and g1t's API
297	is REST. Call it with `curl`, using the job's token and the API's address,
298	which every job has as `GITHUB_API_URL`:
299
300	```yaml
301	- name: Comment on the pull request
302	env:
303	TOKEN: ${{ github.token }}
304	run: \|
305	curl -fsS -X POST "$GITHUB_API_URL/repos/$GITHUB_REPOSITORY/issues/${{ github.event.number }}/comments" \
306	-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
307	-d '{"body": "Built."}'
308	```
309
310	The token reaches this repository and does what the job's `permissions:`
311	say; see [the job's token](#the-jobs-token). The
312	[API reference](/reference/api/) lists every endpoint.
313
314	### Machine sizes
315
316	A job runs on the standard machine unless its `runs-on` names a larger
317	one:
318
319	\| `runs-on` \| vCPUs \| Memory \| Disk \|
320	\| --- \| --- \| --- \| --- \|
321	\| `ubuntu-latest`, or any other Linux label \| 0.5 \| 4 GiB \| 8 GB \|
322	\| `g1t-2core` \| 2 \| 8 GiB \| 16 GB \|
323	\| `g1t-4core` \| 4 \| 12 GiB \| 20 GB \|
324
325	```yaml
326	jobs:
327	build:
328	runs-on: g1t-4core
329	```
330
331	The label can come from the matrix or the run's inputs
332	(`runs-on: ${{ matrix.big && 'g1t-4core' \|\| 'ubuntu-latest' }}`). A
333	larger machine costs what it costs g1t, plus the same margin as all
334	sandbox time: see [usage and billing](/guides/usage-and-billing/#workflow-jobs-on-larger-machines).
335	Builds that compile, such as Rust or a large TypeScript project, finish
336	several times faster on one.
337
338	A job on g1t's machines runs for at most 60 minutes, whatever its
339	`timeout-minutes`; one on a self-hosted runner can run for up to 24 hours.
340	A job stopped at its time cap fails saying so.
341
342	### What a job can reach
343
344	A job's network is restricted, as an agent's is (see
345	[guardrails](/guides/guardrails/)): it reaches the hosts its project's
346	guardrails allow, g1t itself, and what builds need, and nothing else.
347	What builds need is the package registries (npm, PyPI, crates.io, the Go
348	proxy, RubyGems, Packagist, NuGet, Maven and Gradle, Debian's mirrors),
349	GitHub, where `uses:` actions and the setup actions' downloads come from,
350	the toolchains' download sites (`nodejs.org`, `go.dev`,
351	`static.rust-lang.org`), and the public container registries (Docker Hub,
352	GitHub's, Quay, and `mirror.gcr.io`, the mirror of Docker Hub that a job's
353	Engine asks first). A request anywhere else gets `403` with
354	the reason. To reach another host, someone with the Maintain [role](/guides/access-and-roles/) or
355	higher adds it to the project's
356	allowed domains under Settings → Guardrails; a project whose guardrails
357	turn the network restriction off runs its jobs with an open network.
358
359	A host only workflows should reach, such as the API a deploy uploads to,
360	goes in Workflow-only domains instead, limited to the workflows and
361	environments that need it: `api.cloudflare.com \| deploy.yml \| production`
362	lets only `deploy.yml`'s jobs with `environment: production` reach it.
363	Agents never reach those hosts, and neither do runs of pull requests from
364	forks. See [workflow-only domains](/guides/guardrails/#workflow-only-domains).
365
366	g1t does not run cryptocurrency miners: a step that names one (`xmrig`,
367	a `stratum+tcp://` pool, `--donate-level`) is not run, and a job that
368	looks like it is mining is stopped. See
369	[abuse and mining](/guides/guardrails/#abuse-and-mining).
370
371	## Docker
372
373	Each job on g1t's machines has a Docker Engine of its own, inside the
374	job's sandbox. Nothing runs until the job uses it: the first `docker`
375	command, or a job's `services:` or `container:`, starts it, in a second
376	or two, and the log says so. It ends with the job, with every image,
377	container and build cache in it. No other job, repository or workspace
378	ever shares it.
379
380	```yaml
381	jobs:
382	test:
383	runs-on: ubuntu-latest
384	services:
385	postgres:
386	image: postgres:17
387	env:
388	POSTGRES_PASSWORD: ${{ secrets.DB_PASSWORD }}
389	ports: ["5432:5432"]
390	options: >-
391	--health-cmd pg_isready --health-interval 5s --health-retries 10
392	steps:
393	- uses: actions/checkout@v5
394	- run: docker compose up -d --wait
395	- run: npm test
396	env:
397	DATABASE_URL: postgres://postgres:${{ secrets.DB_PASSWORD }}@localhost:5432/postgres
398	```
399
400	### What works
401
402	\| \| On g1t's machines \|
403	\| --- \| --- \|
404	\| `docker build`, `buildx build`, `run`, `exec`, `pull`, `push`, `login`, `compose` \| Work as they do on GitHub's runners. The Engine, Buildx and Compose are current releases. \|
405	\| `services:` \| Pulled and started before the first step, with `env`, `ports`, `volumes`, `options` and `credentials`. Services with a health check are waited for; one that turns unhealthy fails the job with its log. Each service's log is printed when the job ends. `job.services.<id>.id`, `.network` and `.ports` are set. \|
406	\| `container:` \| Every `run` step and JavaScript action runs inside the image, with its `env`, `options`, `volumes` and `credentials`. The workspace, `RUNNER_TEMP` and the tool cache are mounted at the same paths as on g1t's runner. \|
407	\| `uses: docker://image` \| Pulled and run, with `with.args` and `with.entrypoint`. \|
408	\| Docker actions \| Built from the action's Dockerfile (or pulled, for `image: docker://…`), and run with its `args`, `env` and `entrypoint`, its inputs as `INPUT_*` variables, and `pre-entrypoint` and `post-entrypoint`. \|
409	\| `docker/setup-buildx-action` \| Selects the job's own Engine as the builder (BuildKit). Its `name`, `driver`, `platforms` and `nodes` outputs are set. `driver`, `driver-opts` and `buildkitd-*` are not used, and the log says so. \|
410	\| `docker/build-push-action` \| Works, with `push`, `load`, `tags`, `labels`, `build-args`, `secrets`, `target`, `provenance` and `sbom`. \|
411	\| `docker/login-action` \| Works, for g1t's registry, Docker Hub, GitHub's registry, Cloudflare's (`registry.cloudflare.com`) and any registry the job can reach. \|
412
413	### Services and the network
414
415	Every container a job starts shares the job's own network, the one its
416	[guardrails](/guides/guardrails/) apply to. So:
417
418	- A service is at `localhost` on its port, from steps and from other
419	containers. `ports: ["5432:5432"]` and `ports: ["5432"]` both mean
420	`localhost:5432`.
421	- A port mapped to another number (`ports: ["6543:5432"]`, or
422	`docker run -p 8080:80`) is forwarded: `localhost:6543` reaches the
423	service's 5432. `job.services.<id>.ports` says which port to use, and
424	`docker inspect` and `docker port` report it.
425	- A service is also reached by its name, as it is from a job
426	container on GitHub: `postgres:5432` works from steps, from the job's
427	container and from any container started later. So do the names of
428	containers and Compose services, and their network aliases.
429	- Two containers cannot listen on the same port. A job with a
430	`redis` service and a Compose file that starts another Redis on 6379
431	gets an error from the second; give one of them another port.
432
433	A container that asks for `--network none` gets none, and
434	`--network container:<name>` shares that container's.
435
436	### Job containers
437
438	With `container:`, the steps run inside the image as its default user,
439	usually `root`. A few things differ from GitHub's runner:
440
441	- The workspace is at the same path as on g1t's runner
442	(`/home/runner/work/…`), not `/__w`. `github.workspace` is correct
443	either way.
444	- JavaScript actions run inside the container with g1t's Node 24, which
445	needs an image with glibc and `libstdc++` (Debian, Ubuntu and most
446	language images have both). In an image without them, such as Alpine,
447	they run beside the container, on g1t's runner, with the same files,
448	and the log says so.
449	- `actions/checkout`, `actions/cache` and the artifact actions run on
450	g1t's runner, with the same files.
451
452	### Building and pushing images
453
454	On g1t's machines, a job is signed in to g1t's container registry from
455	the start, with its own `G1T_TOKEN`, so it can push to and pull from its
456	repository's images without a login step; images of other repositories
457	need this one added under their
458	[Manage Actions access](/guides/packages/#manage-actions-access). A run that gets no secrets is
459	not signed in. See [container registry](/guides/containers/#in-workflows).
460
461	```yaml
462	jobs:
463	image:
464	runs-on: g1t-4core
465	steps:
466	- uses: actions/checkout@v5
467	- uses: docker/setup-buildx-action@v3
468	- uses: docker/build-push-action@v6
469	with:
470	push: true
471	tags: g1t.sh/${{ github.repository }}:${{ github.sha }}
472	cache-from: type=registry,ref=g1t.sh/${{ github.repository }}:buildcache
473	cache-to: type=registry,ref=g1t.sh/${{ github.repository }}:buildcache,mode=max
474	```
475
476	For other registries, sign in with `docker/login-action` or
477	`docker login`, as on GitHub. Docker Hub's images are pulled through its
478	public mirror first, so jobs are rarely held up by Docker Hub's limits on
479	anonymous pulls.
480
481	#### Caching image builds
482
483	The Engine starts empty in every job, so a build's layers are rebuilt
484	unless the job brings a cache:
485
486	- A registry cache (`cache-to: type=registry,ref=…,mode=max`), in g1t's
487	registry or any other, is the simplest and is shared by every branch.
488	- A local cache (`cache-to: type=local,dest=/tmp/buildx-cache`) saved
489	and restored with `actions/cache`, within [the cache's limits](#the-cache).
490	- `type=gha` is not used on g1t yet: Buildx skips it, and the build
491	runs without a cache.
492
493	### Limits
494
495	- Machine. Containers share the job's machine: its vCPUs, memory and
496	disk ([machine sizes](#machine-sizes)). Image builds and databases want
497	`g1t-2core` or `g1t-4core`. `--cpus` and `--memory` limit a container
498	within that.
499	- Disk. Images take room on the job's disk. On a machine whose disk
500	cannot hold layered images, the Engine stores plain copies, which take
501	more room; the log says when it does.
502	- Linux, amd64. Images for other platforms need QEMU's emulators,
503	which g1t's machines do not have set up; `docker/setup-qemu-action` is
504	not supported there yet.
505	- Privileged containers (`--privileged`) run, with no more reach than
506	the job itself has: the job's sandbox is the boundary.
507
508	### How Docker is kept safe
509
510	- One Engine per job. It runs inside the job's own sandbox, a virtual
511	machine of its own, and is gone with it. No Docker socket of g1t's, or of
512	any machine, is shared with a job.
513	- The job's guardrails hold. Containers use the job's network, so a
514	container, a build step or an image pull reaches only what the job may
515	reach. A host off the list gets `403` with the reason, as any step does.
516	- HTTPS keeps working. In a job whose network is restricted, every
517	container and build step is given the certificate the job's HTTPS is
518	checked with, in `/dev/g1t-egress`, and `SSL_CERT_FILE`,
519	`NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `PIP_CERT`,
520	`GIT_SSL_CAINFO` and `CARGO_HTTP_CAINFO` pointing at it, unless the
521	container sets them itself. None of it is written into an image's layers.
522	Tools that keep their own list of certificates, such as Java's, need it
523	added in the build that uses them.
524	- Short-lived credentials. The registry sign-in uses the run's own
525	token, which ends with the run; `credentials:` for a service or a job
526	container are used for that pull only.
527	- No miners. A container whose image or command names a miner is not
528	created, as a step's script is not run.
529
530	## The cache
531
532	`actions/cache` keeps what a job saves for the repository's later jobs:
533
534	\| \| \|
535	\| --- \| --- \|
536	\| One entry \| Up to 2 GiB, compressed. A larger one is not saved, and the job goes on. \|
537	\| A repository's entries \| Up to 10 GiB together. Saving past it removes the entries restored longest ago. \|
538	\| How long \| Until it has not been restored for 7 days, and at most 28 days after it was saved. \|
539	\| Which branch \| An entry belongs to the branch, tag or pull request whose run saved it. A run restores from its own, then from the branch its pull request merges into, then from the default branch. \|
540	\| Keys \| Written once on each branch: saving under a key that exists there does nothing. On each branch in turn, a restore finds its `key` exactly, else the newest entry whose key starts with one of its `restore-keys`. \|
541	\| `path` \| Files and folders; globs, `**` included; `~/` is the home folder; a line starting with `!` leaves matching paths out. The same key saved for other paths is another entry. \|
542	\| Compression \| zstd. \|
543
544	So a feature branch can read what `main` saved, but `main` never reads
545	what a feature branch saved, and a pull request from outside the
546	repository saves where nothing else ever reads it: nobody can plant an
547	entry that the default branch's builds restore. Actions that cache through the
548	toolkit, such as `actions/setup-node` with `cache: npm`, follow the same
549	rules.
550
551	```yaml
552	- uses: actions/cache@v4
553	with:
554	path: \|
555	~/.cargo/registry/cache
556	target/release
557	!target/**/incremental
558	key: cargo-${{ runner.os }}-${{ hashFiles('Cargo.lock') }}
559	restore-keys: cargo-${{ runner.os }}-
560	```
561
562	Each restore and save says on the job's log how large the entry was and
563	how long it took. A workspace on the plan pays for what its caches and
564	[artifacts](#artifacts) hold (`Actions cache storage` on its statement),
565	at R2's price plus the margin; see
566	[usage and billing](/guides/usage-and-billing/#actions-cache).
567
568	## Artifacts
569
570	`actions/upload-artifact` keeps files a job made with its run, for later
571	jobs, other runs and people:
572
573	\| \| \|
574	\| --- \| --- \|
575	\| One artifact \| Up to 5 GiB, zipped. \|
576	\| A run's artifacts \| Up to 10 GiB together. \|
577	\| How long \| The repository's setting: 14 days unless someone with the Maintain role changes it under Settings → Repository → Artifacts, from 1 to 90 days. `retention-days` asks for fewer days, never more. \|
578	\| Names \| One artifact per name in a run. Uploading a name again fails, unless the upload says `overwrite: true`, which replaces it. A name is up to 256 characters, none of `" : < > \\| * ? \ /`. \|
579	\| `path` \| Files, folders and globs, `**` included; a line starting with `!` leaves matching paths out. Files and folders whose names start with `.` are left out unless `include-hidden-files: true`. \|
580	\| Compression \| `compression-level` 0 (stored) to 9; 6 unless you say. \|
581	\| Outputs \| `artifact-id` (a number), `artifact-url` (its run's page) and `artifact-digest` (the SHA-256 of its zip). \|
582
583	```yaml
584	- uses: actions/upload-artifact@v4
585	with:
586	name: web-dist
587	path: \|
588	dist/
589	!dist/*/.map
590	retention-days: 5
591	compression-level: 9
592	```
593
594	`actions/download-artifact` downloads one by `name` into `path`, or every
595	artifact of the run, each into a folder of its name; `pattern` picks them
596	by name, and `merge-multiple: true` puts them all in one folder.
597	`artifact-ids` picks them by number. With `github-token` and `run-id`, it
598	downloads from another run of the same repository, such as the one a
599	`workflow_run` workflow follows:
600
601	```yaml
602	- uses: actions/download-artifact@v4
603	with:
604	name: web-dist
605	github-token: ${{ secrets.GITHUB_TOKEN }}
606	run-id: ${{ github.event.workflow_run.id }}
607	```
608
609	`actions/upload-artifact/merge` downloads the run's artifacts that match
610	`pattern`, uploads them as one artifact (`name`, `merged-artifacts` unless
611	you say), and deletes them with `delete-merged: true`.
612
613	A run's summary lists its artifacts with their size and when they expire.
614	Anyone who can see the run downloads them there; someone with the Write
615	role can delete one before it expires.
616
617	## Actions built on the toolkit
618
619	Many actions save to the cache with GitHub's toolkit, `@actions/cache`,
620	rather than through `actions/cache`: `actions/setup-node`,
621	`actions/setup-python`, `actions/setup-go` and `actions/setup-java` with
622	`cache:`, `Swatinem/rust-cache`, and others. They work on g1t as they
623	are: every job gets `ACTIONS_RUNTIME_TOKEN`, `ACTIONS_CACHE_URL` and
624	`ACTIONS_RESULTS_URL`, and g1t answers the toolkit's requests from the
625	repository's cache.
626
627	- Their entries are the repository's, under [the cache's](#the-cache)
628	limits, and are deleted the same way.
629	- An entry is restored only by the same kind of save: the toolkit names a
630	version for each entry, from its paths and compression. An entry
631	`setup-node` saved is not restored by `actions/cache`, and the other way
632	round.
633	- An entry the toolkit sends whole, which it does below 128 MB, is not
634	saved when it is over 100 MB, the most g1t takes in one request. The
635	step warns and the job goes on.
636	- The toolkit's artifact library refuses to run against any server but
637	github.com, so an action that uploads artifacts with it directly fails
638	with its own message. `actions/upload-artifact`,
639	`actions/download-artifact` and `actions/upload-artifact/merge` work:
640	g1t runs those itself.
641
642	## Caching Rust builds
643
644	A checkout gives every file a new modification time, so Cargo compiles
645	your workspace's own crates again even when `target/` was restored from
646	the cache. [sccache](https://github.com/mozilla/sccache) caches each
647	compiler call by what it compiles (the source, the flags, the toolchain
648	and the dependencies), so a crate that did not change comes back from the
649	cache instead. Its GitHub Actions backend works on g1t as it is: it keeps
650	its entries in the repository's cache, under [the cache's](#the-cache)
651	limits and branch rules.
652
653	1. Install sccache, pinned to a release and checked against its checksum.
654	2. Set `RUSTC_WRAPPER: sccache` and `SCCACHE_GHA_ENABLED: "true"`. The
655	job's `ACTIONS_RUNTIME_TOKEN` and `ACTIONS_CACHE_URL` are already in
656	every step's environment; no step needs to export them.
657	3. Set `CARGO_INCREMENTAL: "0"`: sccache does not cache incremental
658	builds, and a fresh checkout gains nothing from them.
659
660	```yaml
661	name: CI
662	on:
663	pull_request:
664	push:
665	branches: [main]
666
667	jobs:
668	test:
669	runs-on: ubuntu-latest
670	env:
671	RUSTC_WRAPPER: sccache
672	SCCACHE_GHA_ENABLED: "true"
673	CARGO_INCREMENTAL: "0"
674	steps:
675	- uses: actions/checkout@v5
676	- name: Install sccache
677	env:
678	VERSION: v0.18.0
679	SHA256: 45f1447fbe231e3037bde351ef70677dd212216c8d62ae7ca409fecc4d6acc89
680	run: \|
681	name="sccache-$VERSION-x86_64-unknown-linux-musl"
682	curl -fsSL -o "$RUNNER_TEMP/sccache.tar.gz" \
683	"https://github.com/mozilla/sccache/releases/download/$VERSION/$name.tar.gz"
684	echo "$SHA256 $RUNNER_TEMP/sccache.tar.gz" \| sha256sum -c -
685	tar -xzf "$RUNNER_TEMP/sccache.tar.gz" -C "$RUNNER_TEMP"
686	install -m 0755 "$RUNNER_TEMP/$name/sccache" "$HOME/.cargo/bin/sccache"
687	- run: cargo test --workspace --locked
688	- name: sccache's hits and misses
689	if: always()
690	run: \|
691	echo '```' >> "$GITHUB_STEP_SUMMARY"
692	sccache --show-stats \| tee -a "$GITHUB_STEP_SUMMARY"
693	echo '```' >> "$GITHUB_STEP_SUMMARY"
694	```
695
696	What to expect:
697
698	\| \| \|
699	\| --- \| --- \|
700	\| What is cached \| Every library crate (`rlib`): your workspace's crates and their dependencies. \|
701	\| What is compiled each time \| What rustc links: binaries, `cdylib` crates, proc macros, build scripts and test harnesses. \|
702	\| Its entries \| One per compiled crate, often thousands for a workspace, each a few KB to a few MB. They count toward the repository's 10 GiB like any other entry, and the ones not restored for 7 days are deleted. \|
703	\| Branches \| A pull request reads what the default branch saved. Run the workflow on pushes to the default branch too, as above, or each pull request's first run starts with an empty cache. \|
704	\| Starting over \| Set `SCCACHE_GHA_VERSION` to any new value. A new sccache release starts over by itself. \|
705	\| If the cache cannot be reached \| sccache refuses to start. Set `SCCACHE_IGNORE_SERVER_IO_ERROR: "1"` to have rustc run without it instead. \|
706
707	sccache adds to `actions/cache` rather than replacing it: keep caching
708	`~/.cargo/registry/cache` and `target/` keyed by `Cargo.lock`, so Cargo
709	does not call rustc at all for dependencies that did not change, and
710	sccache answers the calls it still makes for your own crates.
711	`Swatinem/rust-cache` works the same way.
712
713	## OIDC tokens
714
715	A job can prove which repository, branch and environment it runs for with
716	a short-lived OpenID Connect token signed by g1t, and trade it for a cloud
717	provider's credentials. Nothing long-lived needs to sit in a secret.
718
719	1. Give the job, or the workflow, `permissions: id-token: write`. A job
720	without it gets no token, and neither does a run of a pull request from
721	outside the repository.
722	2. Tell your cloud to trust g1t's issuer for your repository (below).
723	3. Use the provider's own login action, which asks for the token.
724
725	```yaml
726	permissions:
727	id-token: write
728	contents: read
729
730	jobs:
731	deploy:
732	runs-on: ubuntu-latest
733	environment: production
734	steps:
735	- uses: aws-actions/configure-aws-credentials@v4
736	with:
737	role-to-assume: arn:aws:iam::123456789012:role/acme-web-deploy
738	aws-region: us-east-1
739	```
740
741	The job gets `ACTIONS_ID_TOKEN_REQUEST_URL` and
742	`ACTIONS_ID_TOKEN_REQUEST_TOKEN`, which `core.getIDToken()` reads. To ask
743	for a token yourself, name its audience:
744
745	```sh
746	curl -sS -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
747	"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://deploy.example.com" \| jq -r .value
748	```
749
750	\| \| \|
751	\| --- \| --- \|
752	\| Issuer \| `https://api.g1t.sh/actions/oidc` \|
753	\| Discovery \| `https://api.g1t.sh/actions/oidc/.well-known/openid-configuration` \|
754	\| Keys \| `https://api.g1t.sh/actions/oidc/.well-known/jwks`, RS256, each with its `kid` \|
755	\| Lifetime \| 5 minutes \|
756	\| Audience \| What the job asks for; `https://g1t.sh/<owner>` when it asks for none \|
757
758	### Claims
759
760	Each token carries the claims GitHub's do, so trust policies written for
761	those read g1t's the same way.
762
763	\| Claim \| Example \|
764	\| --- \| --- \|
765	\| `sub` \| `repo:acme/web:environment:production` for a job with an `environment:`; `repo:acme/web:pull_request` for a pull request's run; otherwise `repo:acme/web:ref:refs/heads/main` (or `refs/tags/v1.2.0`) \|
766	\| `repository`, `repository_owner` \| `acme/web`, `acme` \|
767	\| `repository_id`, `repository_owner_id` \| g1t's ids for them, such as `rep_01kpw0…` \|
768	\| `repository_visibility` \| `public` or `private` \|
769	\| `ref`, `ref_type`, `ref_protected`, `sha` \| `refs/heads/main`, `branch`, `"true"`, the commit \|
770	\| `head_ref`, `base_ref` \| A pull request's branches \|
771	\| `environment` \| The job's environment, when it has one \|
772	\| `event_name` \| `push`, `pull_request`, `workflow_dispatch`, … \|
773	\| `workflow`, `workflow_ref`, `workflow_sha` \| `Deploy`, `acme/web/.g1t/workflows/deploy.yml@refs/heads/main`, the commit \|
774	\| `job_workflow_ref`, `job_workflow_sha` \| The workflow that defines the job: a called workflow's own file \|
775	\| `run_id`, `run_number`, `run_attempt` \| `run_01kq9c…`, `"12"`, `"1"` \|
776	\| `actor`, `actor_id` \| Who started the run \|
777	\| `runner_environment` \| `github-hosted` on g1t's machines, `self-hosted` on yours \|
778	\| `iss`, `aud`, `jti`, `iat`, `nbf`, `exp` \| As in any OIDC token \|
779
780	### AWS
781
782	1. Add g1t as an identity provider, under IAM → Identity providers:
783	provider type OpenID Connect, provider URL
784	`https://api.g1t.sh/actions/oidc`, audience `sts.amazonaws.com`. Or:
785
786	```sh
787	aws iam create-open-id-connect-provider \
788	--url https://api.g1t.sh/actions/oidc \
789	--client-id-list sts.amazonaws.com
790	```
791
792	2. Give the role a trust policy for your repository:
793
794	```json
795	{
796	"Version": "2012-10-17",
797	"Statement": [{
798	"Effect": "Allow",
799	"Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/api.g1t.sh/actions/oidc" },
800	"Action": "sts:AssumeRoleWithWebIdentity",
801	"Condition": {
802	"StringEquals": {
803	"api.g1t.sh/actions/oidc:aud": "sts.amazonaws.com",
804	"api.g1t.sh/actions/oidc:sub": "repo:acme/web:environment:production"
805	}
806	}
807	}]
808	}
809	```
810
811	3. Use `aws-actions/configure-aws-credentials@v4` with `role-to-assume`,
812	as above.
813
814	### Google Cloud
815
816	1. Make a workload identity pool and a provider for g1t:
817
818	```sh
819	gcloud iam workload-identity-pools create g1t --location=global
820	gcloud iam workload-identity-pools providers create-oidc g1t \
821	--location=global --workload-identity-pool=g1t \
822	--issuer-uri=https://api.g1t.sh/actions/oidc \
823	--attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository" \
824	--attribute-condition="assertion.repository_owner == 'acme'"
825	```
826
827	2. Let the repository act as a service account:
828
829	```sh
830	gcloud iam service-accounts add-iam-policy-binding deploy@acme-prod.iam.gserviceaccount.com \
831	--role=roles/iam.workloadIdentityUser \
832	--member="principalSet://iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/g1t/attribute.repository/acme/web"
833	```
834
835	3. Use `google-github-actions/auth@v2` with
836	`workload_identity_provider: projects/123456789/locations/global/workloadIdentityPools/g1t/providers/g1t`
837	and `service_account`. It asks for the provider's own name as the
838	audience, which the provider accepts unless you change its allowed
839	audiences.
840
841	### Azure
842
843	1. On the app registration or user-assigned managed identity, add a
844	federated credential with the scenario Other issuer: issuer
845	`https://api.g1t.sh/actions/oidc`, subject identifier
846	`repo:acme/web:environment:production`, audience
847	`api://AzureADTokenExchange`. Or:
848
849	```sh
850	az ad app federated-credential create --id <application id> --parameters '{
851	"name": "g1t-acme-web-production",
852	"issuer": "https://api.g1t.sh/actions/oidc",
853	"subject": "repo:acme/web:environment:production",
854	"audiences": ["api://AzureADTokenExchange"]
855	}'
856	```
857
858	2. Give it a role on what it deploys to, as for any identity.
859	3. Use `azure/login@v2` with `client-id`, `tenant-id` and
860	`subscription-id`, and no secret.
861
862	A federated credential matches the subject exactly: add one per
863	environment or branch that deploys.
864
865	### Cloudflare
866
867	Cloudflare's API takes API tokens, not OIDC tokens. Keep a token scoped
868	to what the workflow deploys in a secret, available to that workflow only
869	(see [workflow-only domains](/guides/guardrails/#workflow-only-domains)
870	for limiting where it can be sent).
871
872	A Worker of your own can trust g1t's jobs directly, by checking the token
873	a job sends it against g1t's keys:
874
875	```ts
876	import { createRemoteJWKSet, jwtVerify } from "jose";
877
878	const keys = createRemoteJWKSet(new URL("https://api.g1t.sh/actions/oidc/.well-known/jwks"));
879
880	export async function fromG1tJob(request: Request): Promise<boolean> {
881	const token = request.headers.get("authorization")?.replace(/^Bearer /, "") ?? "";
882	const { payload } = await jwtVerify(token, keys, {
883	issuer: "https://api.g1t.sh/actions/oidc",
884	audience: "https://deploy.example.com",
885	});
886	return payload.sub === "repo:acme/web:environment:production";
887	}
888	```
889
890	### npm
891
892	npm's trusted publishing and provenance accept OIDC tokens only from the
893	CI services npm lists, and g1t is not one of them yet. Publish with a
894	granular access token in a secret instead:
895
896	```yaml
897	- uses: actions/setup-node@v4
898	with:
899	node-version: 24
900	registry-url: https://registry.npmjs.org
901	- run: npm publish
902	env:
903	NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
904	```
905
906	See [What g1t can't do yet](/about/limitations/#no-npm-trusted-publishing-or-provenance).
907
908	## Runs and logs
909
910	Open a repository's Actions page, in its sidebar. Pick a workflow to
911	see its runs, run it by hand if it has `workflow_dispatch`, or turn it off
912	without touching its file.
913
914	A run's page opens on its Summary. Its sidebar lists All jobs;
915	pick one to see its steps and their logs as they are written. Groups
916	fold, errors and warnings are marked, and secrets are replaced with
917	`***`. The page keeps itself up to date while the run goes on.
918
919	The start of each job's log lists what its [token](#the-jobs-token) may do.
920
921	### The run's summary
922
923	The summary holds, top to bottom:
924
925	\| Part \| What it shows \|
926	\| --- \| --- \|
927	\| The run \| What triggered it and when, who, the commit and its branch (or pull request), how the run stands, how long it took in all, and how many artifacts it kept. \|
928	\| The jobs graph \| The workflow file and its event (`deploy.yml · on: push`), then every job and how they depend on each other. See [the jobs graph](#the-jobs-graph). \|
929	\| Annotations \| Every job's errors, warnings and notices, counted by kind, each with the job it came from. Folds away. \|
930	\| Job summaries \| What each job's steps wrote to `$GITHUB_STEP_SUMMARY`, under `<job> summary`. See [job summaries](#job-summaries). \|
931	\| Artifacts \| What the run kept, to download. The count in the run's card jumps here. \|
932
933	Under Run details in the sidebar, Workflow file opens the
934	workflow as it was at the run's commit.
935
936	### The jobs graph
937
938	Jobs are laid out left to right by their `needs:`: a job that needs
939	nothing starts a row on the left, and each job sits one column to the
940	right of the furthest job it needs. Within a column, jobs are ordered so
941	that as few connectors as possible cross.
942
943	\| Node \| How it shows \|
944	\| --- \| --- \|
945	\| A job \| Its status, its name and how long it took. Click it to open its steps and logs. \|
946	\| A job that deploys \| Its environment's address (`environment.url`), as a link, under its name. \|
947	\| A matrix \| One node with how many jobs it made (`test · 6 jobs`) and how they stand together. Click it to list each combination; click one to open it. \|
948	\| A reusable workflow \| A box under the job that calls it, named with the called file, holding the called workflow's jobs laid out the same way. The jobs that need the calling job connect to the box. \|
949
950	Connectors run from a job to each job that needs it. They are red from a
951	job that failed, and move while the job they lead to is running (they
952	stay still if your system asks for reduced motion).
953
954	A wide graph scrolls sideways inside its card, on a phone as on a desktop.
955
956	The sidebar groups jobs the same way: a matrix's jobs, and a called
957	workflow's jobs, fold under their name.
958
959	### Job summaries
960
961	Markdown a step appends to the file in `$GITHUB_STEP_SUMMARY` shows on
962	the run's summary, below the graph, a card per job, in the order its
963	steps wrote it. The card's title opens the job:
964
965	```yaml
966	- name: Report the tests
967	if: always()
968	run: \|
969	echo "### Test results" >> "$GITHUB_STEP_SUMMARY"
970	echo "\| Suite \| Passed \| Failed \|" >> "$GITHUB_STEP_SUMMARY"
971	echo "\| --- \| ---: \| ---: \|" >> "$GITHUB_STEP_SUMMARY"
972	echo "\| unit \| 41 \| 0 \|" >> "$GITHUB_STEP_SUMMARY"
973	```
974
975	\| What \| How it works \|
976	\| --- \| --- \|
977	\| Formatting \| GitHub-flavoured Markdown: tables, task lists, alerts such as `> [!WARNING]`, code blocks, and the HTML GitHub allows. Scripts, styles and event handlers are removed. \|
978	\| Secrets \| Masked like the log, before the summary leaves the runner. \|
979	\| Size \| Up to 1 MiB a step. A larger summary is refused with an error in the step's log, as on GitHub. \|
980	\| Steps \| Up to 20 steps of a job keep a summary; later ones are dropped. \|
981	\| Actions \| A JavaScript action's `core.summary` writes to the same file, so it works unchanged. \|
982
983	Summaries belong to their attempt: an earlier attempt keeps its own.
984
985	### Re-running
986
987	When a run has finished, someone with the Write role can run it again:
988
989	\| Button \| Runs again \|
990	\| --- \| --- \|
991	\| Re-run all jobs \| Every job. \|
992	\| Re-run failed jobs \| Jobs that did not succeed (failed, cancelled or skipped), and every job that needs one of them. \|
993	\| The re-run button beside a job's name \| That job, and every job that needs it. A job of a matrix runs again with the rest of its matrix; a job of a reusable workflow runs again with the job that calls it. \|
994
995	Jobs that are not run again keep how they ended, and their outputs reach
996	the jobs that need them.
997
998	Each re-run is a new attempt. The run keeps its number, `github.run_attempt`
999	goes up by one, and the attempt before is kept as it ended: its jobs,
1000	their steps, logs and summaries. Pick one from Attempt # at the top of
1001	the page to read it. Its jobs have ids of their own, so a link to an
1002	earlier attempt's job keeps showing that job's log.
1003
1004	#### Debug logging
1005
1006	Each re-run asks whether to Enable debug logging. The new attempt's
1007	jobs then run with:
1008
1009	\| Set \| Effect \|
1010	\| --- \| --- \|
1011	\| `RUNNER_DEBUG=1`, and `runner.debug` is `1` \| Actions that check it, such as the toolkit's `core.isDebug()`, log more. \|
1012	\| `ACTIONS_STEP_DEBUG=true` \| `::debug::` lines are shown in the log. \|
1013	\| `ACTIONS_RUNNER_DEBUG=true` \| Set for actions that read it. \|
1014
1015	With debug logging, each step's log also says how its `if:` read:
1016	`Evaluating condition for step`, the expression, and the result. Setting a
1017	secret or variable named `ACTIONS_STEP_DEBUG` to `true` shows `::debug::`
1018	lines on every run instead. The attempt picker marks attempts that ran
1019	with debug logging.
1020
1021	### Cancelling
1022
1023	Cancel run cancels jobs that have not started at once. A job that is
1024	running is stopped the way GitHub stops one:
1025
1026	1. The step it is on gets `SIGINT`, then `SIGTERM` 7.5 seconds later, and
1027	is killed 2.5 seconds after that. Signals reach the processes the step
1028	started too; in a [job container](#job-containers) they reach only the
1029	`docker exec` that runs the step. The step ends cancelled.
1030	2. Its remaining steps run only if they ask to: `if: always()` or
1031	`if: cancelled()`. Steps without an `if:`, or with `success()` or
1032	`failure()`, are skipped.
1033	3. Post steps (an action's `post`, saving the cache) run, as their
1034	`post-if` is `always()` unless the action says otherwise.
1035	4. The job ends cancelled, whatever those steps came to.
1036
1037	While that happens the run says Cancelling. A job still going 5
1038	minutes after it was cancelled is stopped outright. Force cancel
1039	(shown while a run is cancelling) stops every job at once, without
1040	waiting for its cleanup steps.
1041
1042	A step learns of a cancellation within about 10 seconds, even when it
1043	prints nothing. A job on a [self-hosted runner](/guides/self-hosted-runners/)
1044	is stopped the same way.
1045
1046	### Searching and downloading logs
1047
1048	The Search logs box above a job's steps shows only the lines that hold
1049	what you type, in any case, with each match marked and every step that has
1050	one opened. Lines inside folded groups are searched too.
1051
1052	\| Download \| Where \|
1053	\| --- \| --- \|
1054	\| One job's whole log, as text \| The download button beside the job's name. \|
1055	\| Every job's log of an attempt, as a zip \| Download logs at the top of the run. The zip holds `1_<job>.txt` with each job's whole log, and a `<job>/` folder with `<step>_<step name>.txt` for each step. \|
1056
1057	A zip holds up to 24 MiB of logs; jobs past that are listed with a note
1058	to download them on their own. Each job keeps up to 4 MB of log.
1059
1060	### Status badges
1061
1062	A badge shows how a workflow's latest finished run went: passing,
1063	failing, cancelled, or no status before it has finished one.
1064
1065	1. Open the repository's Actions page and pick the workflow.
1066	2. Click Create status badge.
1067	3. Choose a branch and an event, if you want them, and copy the Markdown.
1068
1069	```markdown
1070	[![CI](https://g1t.sh/acme/web/actions/workflows/ci.yml/badge.svg)](https://g1t.sh/acme/web/actions?workflow=ci.yml)
1071	```
1072
1073	The address is `https://g1t.sh/{workspace}/{repo}/actions/workflows/{file}/badge.svg`,
1074	where `{file}` is the workflow's file name in `.g1t/workflows/`. It takes:
1075
1076	\| Parameter \| Shows \|
1077	\| --- \| --- \|
1078	\| `branch` \| Runs on that branch. Without it, the default branch's runs, or any branch's when the default branch has none. \|
1079	\| `event` \| Runs started by that event, such as `push` or `pull_request`. \|
1080
1081	A public repository's badge loads for anyone and is cached for a minute.
1082	A private repository's loads only for someone who can see the repository,
1083	so it does not show in a README read anywhere else.
1084
1085	### Masking secrets
1086
1087	Every secret's value is replaced with `***` wherever a job prints it, and
1088	so is every value a step masks with `::add-mask::`. Each is masked in the
1089	forms it shows up in:
1090
1091	\| Form \| Example \|
1092	\| --- \| --- \|
1093	\| As it is \| `echo $API_KEY` \|
1094	\| Each of its lines on its own \| `cat key.pem`, which prints a private key a line at a time \|
1095	\| Base64 \| `echo -n $API_KEY \\| base64`, or an `Authorization: Basic` header \|
1096	\| JSON-escaped \| A secret holding quotes or newlines printed inside JSON \|
1097
1098	Annotations' titles and messages, and step names, are masked the same way.
1099	A job output that holds a secret in any of those forms is left out, with
1100	a warning in the log, since outputs go to other jobs and to the run's page.
1101	A value of one character is not masked: it would hide that character
1102	everywhere.
1103
1104	## Pull requests
1105
1106	A pull request's workflows run on each new head: when it is opened, when
1107	a commit is pushed to it, and, for one g1t makes, when g1t
1108	marks it ready, which on g1t is when it first has code. Each head runs
1109	each workflow once.
1110
1111	They also start on the activity types `reopened` (also run by
1112	default, as `opened` and `synchronize` are), `converted_to_draft`,
1113	`ready_for_review`, `labeled`, `unlabeled`, `milestoned`, `demilestoned`,
1114	`assigned`, `review_requested` and `closed`, and `edited` when the branch
1115	a pull request merges into changes; `issue_comment` workflows on
1116	`created`, `edited` (with `github.event.changes.body.from`) and `deleted`; `issues` workflows on `labeled`, `unlabeled`, `milestoned` and
1117	`demilestoned` too. List them under `types:` to run on them. For
1118	`labeled` and `unlabeled`, `github.event.label` names the label. A pull
1119	request's `branches` filter, `github.base_ref` and
1120	`pull_request.base.ref` are the branch it merges into, which is not
1121	always the default branch: see
1122	[pull requests into other branches](/guides/base-branches/).
1123
1124	A pull request from outside the workspace may wait for approval before
1125	its workflows run: see [pull requests from outside](#pull-requests-from-outside).
1126
1127	`github.event.pull_request` reads as it does on GitHub. For a pull request
1128	g1t made, `pull_request.user` is g1t (`login` `g1t`, `type` `Bot`), and
1129	`pull_request.requested_by` names the person who asked for it; it is `null`
1130	on anyone else's. `github.event.issue.requested_by` does the same for an
1131	issue g1t's agent filed. `sender` is whoever caused the event.
1132
1133	## Checks
1134
1135	A pull request's checks are its workflows. Each workflow that runs on
1136	`pull_request` runs on every pull request's head, whoever opened it, a
1137	person or an agent, and its runs report a check named after the workflow:
1138	a workflow with `name: CI` reports `CI`, with the status context
1139	`CI / pull_request` (the workflow's name and the event). Each of its jobs
1140	is a [check run](/guides/checks/) on the commit, shown as
1141	`CI / test (pull_request)` beside it wherever it appears.
1142
1143	- Which checks a merge needs is up to the [rules](/guides/rules/) of the branch it merges into,
1144	their [required status checks](/guides/pull-requests/#required-status-checks),
1145	under Settings → Rules. A required check that failed,
1146	is still running or has not reported holds the merge. Checks that are not
1147	required are shown on the pull request and never hold it.
1148	- In a repository that merges through the [merge queue](/guides/merge-queue/),
1149	workflows with `on: merge_group` run on each combined state the queue
1150	builds, on the branch `g1t-queue/<entry>`, and the state lands only if
1151	they and every required check pass on it. A workflow behind a required
1152	check needs `merge_group` in its `on:`.
1153	- A pull request g1t is working on goes back to g1t when
1154	a check fails, with the end of each failed job's log. The agent reads the
1155	run and its logs with the same tools you have, fixes the cause, and
1156	pushes; the workflows run again. See
1157	[seeing it through](/guides/working-with-g1t/#seeing-it-through).
1158
1159	```yaml
1160	name: CI
1161
1162	on:
1163	pull_request:
1164	push:
1165	branches: [main]
1166	merge_group:
1167	```
1168
1169	### Add CI
1170
1171	A repository with no workflows has nothing that proves a change works, for
1172	people or for agents. Its pull requests, its Branches and merging
1173	settings and its Actions page say This repository has no checks,
1174	with an Add CI button. Anyone who can push to the repository can use it:
1175
1176	1. Choose Add CI. g1t looks at the files at the repository's root and
1177	writes a starter workflow with a job for each stack it finds, up to
1178	three: Node (npm, pnpm, Yarn or Bun), Rust, Go, Python (pip or uv), Ruby,
1179	Java (Maven or Gradle), .NET, or Make. Each job installs, lints where
1180	the project says how, builds and tests. When it finds none, the job is a
1181	placeholder that fails until you replace its last step with your own
1182	commands.
1183	2. The workflow is committed as `.g1t/workflows/ci.yml` on a new branch,
1184	`add-ci`, and opened as a pull request, by you. It is named `CI` and runs
1185	on `pull_request`, on `push` to the default branch, and on `merge_group`.
1186	3. Change it on the pull request if the steps are not how your project
1187	builds, and merge it.
1188	4. Once it has run, `CI` is offered under **Require status checks to pass
1189	before merging**.
1190	Require it, so that nothing merges into the default branch unless it
1191	passes.
1192
1193	## Secrets and variables
1194
1195	Secrets are read as `${{ secrets.KEY }}` and config as `${{ vars.KEY }}`,
1196	from the rows under Settings → Secrets and variables that are
1197	available to Workflows. A job with `environment: production` reads each
1198	key's Production row; other jobs read the rows for all environments. A
1199	job with an `environment:` also makes a deployment to it; see
1200	[deployments from g1t Actions](/guides/deployments-api/#deployments-from-g1t-actions). See
1201	[Secrets and variables](/guides/secrets-and-variables/) for how rows,
1202	environments and the workspace's rows work.
1203
1204	Every job also gets `${{ secrets.G1T_TOKEN }}`, [its own token](#the-jobs-token),
1205	with `GITHUB_TOKEN` as its alias. A pull request's runs get secrets only
1206	when its author has the Write [role](/guides/access-and-roles/) or higher
1207	on the repository, a member or an outside collaborator, or is g1t working
1208	on its own. For a pull request g1t made, its author is g1t and the person
1209	who asked for it is the one whose role counts. Anyone else's, such as one
1210	from a fork or by someone with Read or Triage, runs without secrets and
1211	with a token that can only read. See
1212	[who gets secrets](/guides/secrets-and-variables/#who-gets-secrets).
1213
1214	## The job's token
1215
1216	Each job gets a token of its own, `${{ secrets.G1T_TOKEN }}`
1217	(`${{ secrets.GITHUB_TOKEN }}` and `${{ github.token }}` are the same).
1218	`actions/checkout` uses it, and so can any step that calls the
1219	[API](/reference/api/) or pushes with git:
1220
1221	- It reaches this repository only. Every other repository, even one
1222	in the same workspace, is refused. So are packages: it reaches this
1223	repository's own, and another package only once the package's admins
1224	add this repository under its
1225	[Manage Actions access](/guides/packages/#manage-actions-access).
1226	- It can do what its `permissions:` say, and nothing more.
1227	- It stops working when the job ends, however it ends.
1228	- Everything it changes is in the [audit log](/guides/audit-log/) as that
1229	job's, under its run.
1230	- What it changes starts no workflows: a push, a pull request, an issue
1231	or a comment made with it runs nothing, so a workflow cannot set itself
1232	off. `workflow_dispatch` and [`repository_dispatch`](#repository-dispatch)
1233	are the exceptions, for a workflow that means to start another.
1234	- It never puts g1t to work. A comment it posts that mentions
1235	`@g1t` starts nothing, and it cannot assign an issue or a plan to g1t,
1236	queue one for it, hand it work or ask it for a review. Otherwise a
1237	workflow that asks g1t to fix a failing check would run again on g1t's
1238	push, and ask again, without end. A step that should put g1t to work
1239	uses a token of a person's own, stored as a
1240	[secret](/guides/secrets-and-variables/).
1241
1242	`permissions:` goes at the top of the workflow, for every job, or on a job,
1243	which then ignores the workflow's. Once either is written, every permission
1244	it leaves out is `none`:
1245
1246	```yaml
1247	permissions:
1248	contents: read
1249
1250	jobs:
1251	release:
1252	runs-on: ubuntu-latest
1253	permissions:
1254	contents: write
1255	pull-requests: write
1256	steps:
1257	- uses: actions/checkout@v5
1258	- run: ./scripts/release.sh
1259	```
1260
1261	\| Permission \| `read` lets it \| `write` also lets it \|
1262	\| --- \| --- \| --- \|
1263	\| `contents` \| Clone and fetch with git, read the repository \| Push, publish releases \|
1264	\| `pull-requests` \| Read pull requests \| Open, review, close and merge them \|
1265	\| `issues` \| Read issues \| Open, edit, comment on and close them \|
1266	\| `actions` \| Read workflows, runs and logs \| Run, cancel and re-run them \|
1267	\| `checks`, `statuses` \| Read statuses and check runs \| Report them \|
1268	\| `deployments`, `pages` \| Read deployments \| Report them \|
1269	\| `packages` \| Pull packages \| Push and publish them \|
1270	\| `security-events` \| Read security alerts \| Upload code scanning results, change alerts \|
1271	\| `metadata` \| Always `read` \| \|
1272	\| `id-token` \| Nothing \| Ask for an [OIDC token](#oidc-tokens) \|
1273	\| `discussions`, `attestations`, `models`, `repository-projects` \| Nothing on g1t \| Nothing on g1t \|
1274
1275	`read-all` and `write-all` set every permission; `permissions: {}` sets
1276	none, so the token cannot even clone a private repository. A reusable
1277	workflow's jobs get no more than the job that calls it.
1278
1279	There is no `workflows` permission for a job's token: it can never add,
1280	change or delete a file under `.g1t/workflows/` or `.github/workflows/`,
1281	even with `contents: write`. A push that does is declined, naming the file,
1282	so a workflow cannot rewrite the workflows that run with its repository's
1283	secrets. To change workflows from a job, push with a
1284	[personal access token](/guides/authentication/#workflow-files) that has
1285	Workflow files: write, kept as a secret.
1286
1287	The job's token is the repository's workspace acting with the Write role
1288	at most, never Admin: it cannot manage webhooks, secrets, deploy keys or who
1289	has access, whatever it asks for.
1290
1291	Without `permissions:` a job gets the repository's default, which
1292	someone with the Admin role sets under Settings → Actions:
1293
1294	\| Repository \| Default until someone chooses \|
1295	\| --- \| --- \|
1296	\| Made before restricted tokens came in, in October 2026 \| Read and write: every permission at `write`, as before \|
1297	\| Made since \| The workspace's default for new repositories: Read repository contents and packages (`contents: read`, `packages: read`) unless an owner chose otherwise \|
1298
1299	The workspace's owners set that default, and a maximum, under the
1300	workspace's Settings → Actions: with a maximum of Read only, no
1301	repository's default goes past `contents: read` and `packages: read`,
1302	whatever it chose. Workflows that write `permissions:` get what they
1303	write either way, and whatever a workflow asks for, a pull request from
1304	outside the repository's writers (a fork, or someone with Read or Triage)
1305	gets a token that can only read.
1306
1307	Allow g1t Actions to create and approve pull requests is off unless a
1308	repository's admin turns it on under Settings → Actions, and they can
1309	only where the workspace's owners allow it. Until then a job's token
1310	cannot open a pull request or approve one, whatever its `pull-requests`
1311	permission says; it can still read, comment on, review with changes
1312	requested, and merge them.
1313
1314	The token can never change secrets, variables, environments' rules or
1315	the Actions settings, approve runs or deployments, or reach another
1316	repository.
1317
1318	## Environments
1319
1320	A job that names an environment with `environment:` reads that
1321	environment's [secrets and variables](/guides/secrets-and-variables/#a-value-per-environment)
1322	and records a [deployment](/guides/deployments-api/#deployments-from-g1t-actions)
1323	to it. Give the environment protection rules, and such a job waits until
1324	they let it through, and only then gets the environment's secrets:
1325
1326	\| Rule \| What it does \|
1327	\| --- \| --- \|
1328	\| Required reviewers \| Up to 6 people or teams. The job waits until one of them approves it. \|
1329	\| Prevent self-review \| Whoever started the run cannot approve it, even as a reviewer. \|
1330	\| Wait timer \| Minutes the job waits once it reaches the environment, up to 43,200 (30 days). \|
1331	\| Deployment branches and tags \| All branches; Protected branches only, those the repository's [rules](/guides/rules/) protect, the default branch included; or Selected branches and tags, by pattern, such as `main`, `release/` or `v`. A job on any other ref fails, saying so. A pull request's run is on no branch, so it can deploy only where all branches may. \|
1332	\| Allow admins to bypass \| On unless you turn it off: someone with the Admin role may approve without being a reviewer, which also skips the wait timer. \|
1333
1334	To set them:
1335
1336	1. Open the repository's Settings → Environments. It lists every
1337	environment your workflows, secrets and deployments name.
1338	2. Choose one, or name a new one, and set its rules.
1339	3. Save. Runs that reach the environment from then on wait by them.
1340
1341	A run whose jobs wait shows Waiting for review at the top of its page,
1342	with the environments, the jobs each holds, its reviewers and when its
1343	wait timer runs out. Reviewers are told in their [notifications](/guides/notifications/);
1344	on the run's page they choose Approve and deploy or Reject, with
1345	room for a comment. One review covers every job of the run that names the
1346	environment. A rejected job fails, and so does anything that needs it. The
1347	rest of the run goes on meanwhile: jobs that do not need the waiting ones
1348	run.
1349
1350	The environment's name may be an expression, such as
1351	`environment: ${{ inputs.target }}`: it is read once the job's needs are
1352	done, and its rules and secrets are that environment's. Names are matched
1353	without regard to case.
1354
1355	From the API, `PUT /repos/{owner}/{repo}/environments/{environment}` sets
1356	the rules, with `reviewers`, `prevent_self_review`, `wait_timer`,
1357	`deployment_branch_policy`, `branch_policies` and `can_admins_bypass`;
1358	`GET` on the same route returns them as `protection_rules`; `DELETE`
1359	removes them. `POST /repos/{owner}/{repo}/actions/runs/{id}/pending_deployments`
1360	approves or rejects a run's waiting jobs:
1361
1362	```sh
1363	curl -X PUT https://api.g1t.sh/repos/acme/web/environments/production \
1364	-H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
1365	-d '{"reviewers": [{"type": "Team", "name": "deployers"}], "wait_timer": 10,
1366	"deployment_branch_policy": {"protected_branches": true, "custom_branch_policies": false}}'
1367	```
1368
1369	A job's own token cannot approve, reject or change any of it.
1370
1371	## Pull requests from outside
1372
1373	A pull request from someone outside the workspace runs code anyone could
1374	have written. By the repository's approval policy, its runs wait as
1375	Approval required until someone with the Write
1376	[role](/guides/access-and-roles/) chooses Approve and run on the run's
1377	page. Nothing runs before then: no job starts, and no token or secret is
1378	handed out.
1379
1380	\| Policy, under Settings → Actions \| Whose pull requests' runs wait \|
1381	\| --- \| --- \|
1382	\| First-time contributors \| Someone outside the workspace who has not had a pull request merged here yet. \|
1383	\| Outside contributors (the default) \| Those, and everyone outside the workspace who cannot push here: pull requests from forks, and from people with Read or Triage. \|
1384	\| All external contributors \| Everyone outside the workspace, [outside collaborators](/guides/access-and-roles/#outside-collaborators) with Write included. \|
1385
1386	Members' pull requests never wait, nor do pull requests g1t opens on its
1387	own. For a pull request g1t made for someone, that person is the one whose
1388	policy counts. Each new push to the pull request waits again.
1389	`pull_request_target` runs, which run the default branch's workflow and
1390	code, never wait.
1391
1392	From the API: `POST /repos/{owner}/{repo}/actions/runs/{id}/approve`
1393	approves a run, and `GET` and `PUT
1394	/repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approval`
1395	read and set the policy, as `approval_policy`.
1396
1397	## Repository dispatch
1398
1399	`POST /repos/{owner}/{repo}/dispatches` starts the default branch's
1400	workflows that run `on: repository_dispatch` for its `event_type`, those
1401	listing it under `types:` or listing none. `client_payload` is theirs to
1402	read as `github.event.client_payload`:
1403
1404	```yaml
1405	on:
1406	repository_dispatch:
1407	types: [docs-published]
1408
1409	jobs:
1410	announce:
1411	runs-on: ubuntu-latest
1412	steps:
1413	- run: echo "Docs ${{ github.event.client_payload.version }} are out"
1414	```
1415
1416	```sh
1417	curl -X POST https://api.g1t.sh/repos/acme/web/dispatches \
1418	-H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
1419	-d '{"event_type": "docs-published", "client_payload": {"version": "2.4.0"}}'
1420	```
1421
1422	It needs the Write role, or a token with `code:write`; a job's own token
1423	needs `contents: write`. `client_payload` is a JSON object of at most 10
1424	properties and 64 KB.
1425
1426	## Who may run workflows
1427
1428	What you can do with a repository's workflows follows your
1429	[role](/guides/access-and-roles/) on it:
1430
1431	\| \| Needs \|
1432	\| --- \| --- \|
1433	\| See workflows, runs and their logs \| Read: on a public repository, anyone \|
1434	\| Run a workflow by hand, cancel or re-run a run, approve a pull request's run from outside \| Write \|
1435	\| Approve or reject a job waiting for an environment \| One of the environment's reviewers \|
1436	\| Enable or disable a workflow \| Maintain \|
1437	\| The repository's secrets and variables, seeing them included; environments' rules; Settings → Actions \| Admin \|
1438
1439	Jobs run in g1t's sandboxes, so they need the
1440	[g1t plan](/guides/usage-and-billing/#the-g1t-plan) or
1441	[the trial](/guides/usage-and-billing/#the-trial); jobs on
1442	[self-hosted runners](/guides/self-hosted-runners/#billing) need neither.
1443	On a public repository,
1444	[g1t's open-source pool](/guides/usage-and-billing/#the-open-source-pool)
1445	runs them too, after a card check, until the month's pool is spent.
1446
1447	Before each job starts, g1t reserves what it may cost (its time limit at
1448	the sandbox price) with billing, and settles what it really cost when it
1449	ends; each job's sandbox is charged as
1450	[sandbox time](/guides/usage-and-billing/#sandbox-time), from the first
1451	second. A job billing refuses does not start: it is recorded as failed
1452	with "Not started:" and the reason, such as "Workflows run in g1t's
1453	sandboxes, which cost real money, so they need the g1t plan ($20 a month)
1454	or a card check", and what to do about it. The
1455	Actions page tells people with Write on a repository whose workspace
1456	cannot run jobs before the first run.
1457
1458	## From the API
1459
1460	The routes follow the standard Actions REST shape, so existing scripts
1461	usually work once they point at `https://api.g1t.sh`.
1462
1463	\| `workflow` action \| Route \|
1464	\| --- \| --- \|
1465	\| `list` \| `GET /repos/{owner}/{repo}/actions/workflows` \|
1466	\| `list_runs` \| `GET /repos/{owner}/{repo}/actions/runs`, with `workflow`, `branch`, `event`, `pull`, `head_sha` \|
1467	\| `get_run` \| `GET /repos/{owner}/{repo}/actions/runs/{id}` \|
1468	\| `job_logs` \| `GET /repos/{owner}/{repo}/actions/jobs/{job}/logs?after=`, or `?format=text` for the whole log as plain text \|
1469	\| `get_run` with `attempt` \| `GET /repos/{owner}/{repo}/actions/runs/{id}/attempts/{attempt}` \|
1470	\| No tool: a download \| `GET /repos/{owner}/{repo}/actions/runs/{id}/logs`, or `…/attempts/{attempt}/logs`: every job's log as a zip \|
1471	\| `dispatch` \| `POST /repos/{owner}/{repo}/actions/workflows/{workflow}/dispatches` with `ref` and `inputs` \|
1472	\| `cancel` \| `POST /repos/{owner}/{repo}/actions/runs/{id}/cancel`; `…/force-cancel`, or `force`, to stop running jobs without their cleanup steps \|
1473	\| `rerun` \| `POST …/runs/{id}/rerun`, or `…/rerun-failed-jobs`; one job and those that need it with `POST /repos/{owner}/{repo}/actions/jobs/{job}/rerun`. Each takes `enable_debug_logging` (or `debug`) \|
1474	\| `update` \| `PUT …/workflows/{workflow}/enable` and `…/disable` \|
1475	\| `approve_run` \| `POST /repos/{owner}/{repo}/actions/runs/{id}/approve` \|
1476	\| `pending_deployments` \| `GET /repos/{owner}/{repo}/actions/runs/{id}/pending_deployments` \|
1477	\| `review_deployments` \| `POST /repos/{owner}/{repo}/actions/runs/{id}/pending_deployments` with `environment_names`, `state` and `comment` \|
1478	\| `get_environment` \| `GET /repos/{owner}/{repo}/environments/{environment}` \|
1479	\| `update_environment` \| `PUT /repos/{owner}/{repo}/environments/{environment}` \|
1480	\| `delete_environment` \| `DELETE /repos/{owner}/{repo}/environments/{environment}` \|
1481	\| `get_permissions`, `set_permissions` \| `GET` and `PUT /repos/{owner}/{repo}/actions/permissions/workflow`, with `default_workflow_permissions` (`read`, `write` or `inherit`) and `can_approve_pull_request_reviews` \|
1482	\| `get_workspace_permissions`, `set_workspace_permissions` \| `GET` and `PUT /workspaces/{workspace}/actions/permissions/workflow`, with `default_workflow_permissions`, `max_workflow_permissions` and `can_approve_pull_request_reviews` \|
1483	\| `get_approval_policy`, `set_approval_policy` \| `GET` and `PUT /repos/{owner}/{repo}/actions/permissions/fork-pr-contributor-approval` \|
1484	\| `get_access`, `set_access` \| `GET` and `PUT /repos/{owner}/{repo}/actions/permissions/access`, with `access_level` (`none` or `organization`) \|
1485	\| `repository_dispatch` \| `POST /repos/{owner}/{repo}/dispatches` with `event_type` and `client_payload` \|
1486	\| `list_artifacts` \| `GET /repos/{owner}/{repo}/actions/artifacts`, with `name`, `page`, `per_page` \|
1487	\| `run_artifacts` \| `GET …/actions/runs/{id}/artifacts`, with `name` \|
1488	\| `get_artifact` \| `GET …/actions/artifacts/{artifact_id}` \|
1489	\| `download_artifact` \| `GET …/actions/artifacts/{artifact_id}/zip`: a `302` to a link good for 10 minutes \|
1490	\| `delete_artifact` \| `DELETE …/actions/artifacts/{artifact_id}` \|
1491	\| `artifact_retention`, `set_artifact_retention` \| `GET` and `PUT …/actions/permissions/artifact-and-log-retention` with `days` (it sets artifacts' days only; logs are kept with their run) \|
1492
1493	Secrets and variables have a tool of their own, `secret`:
1494
1495	\| `secret` action \| Route \|
1496	\| --- \| --- \|
1497	\| `list_secrets`, `set_secret`, `delete_secret` \| `GET /repos/{owner}/{repo}/actions/secrets`, `PUT` and `DELETE …/secrets/{name}` \|
1498	\| `list_variables`, `set_variable`, `delete_variable` \| `GET` and `POST /repos/{owner}/{repo}/actions/variables`, `PATCH` and `DELETE …/variables/{name}` \|
1499
1500	Workspace secrets and variables are under
1501	`/workspaces/{workspace}/actions/secrets` and `…/variables`. The fields
1502	g1t adds (environments, who reads a row, linked repositories) are in
1503	[Secrets and variables](/guides/secrets-and-variables/#from-the-api).
1504
1505	```sh
1506	curl -X POST https://api.g1t.sh/repos/acme/web/actions/workflows/ci.yml/dispatches \
1507	-H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \
1508	-d '{"ref": "main", "inputs": {"environment": "staging"}}'
1509	```
1510
1511	To save an artifact from a script, follow the redirect:
1512
1513	```sh
1514	curl -L -o web-dist.zip -H "Authorization: Bearer $G1T_TOKEN" \
1515	https://api.g1t.sh/repos/acme/web/actions/artifacts/4182/zip
1516	```