| 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 | g1t never reads `.github`. A repository mirrored to both places can keep |
| 23 | `.github` for GitHub and `.g1t` for g1t, side by side. |
| 24 | |
| 25 | Then add your [secrets and variables](#secrets-and-variables): GitHub never |
| 26 | gives their values out, so they cannot be copied across. |
| 27 | |
| 28 | ## What runs |
| 29 | |
| 30 | | On GitHub | On g1t | |
| 31 | | --- | --- | |
| 32 | | `on:` `push` (branches, tags, paths), `pull_request`, `pull_request_target`, `issues`, `issue_comment`, `pull_request_review`, `schedule`, `workflow_dispatch`, `workflow_run`, `merge_group` | The same, from g1t's own pushes, pull requests, issues, comments and [merge queue](/guides/merge-queue/). | |
| 33 | | `jobs`, `needs`, `if`, `outputs`, `env`, `defaults`, `timeout-minutes`, `continue-on-error` | The same. | |
| 34 | | `strategy.matrix` with `include` and `exclude`, `fail-fast`, `max-parallel`, a matrix from `fromJSON(needs.…)` | The same. | |
| 35 | | `concurrency` with `cancel-in-progress` | The same. | |
| 36 | | `${{ }}` expressions: every operator, function and context | The same, including `hashFiles`, `success()`, `failure()`, `always()` and `cancelled()`. | |
| 37 | | `run:` with `bash`, `sh`, `python` or a custom shell | The same. | |
| 38 | | JavaScript actions (`uses: owner/repo@v7`) | Fetched from GitHub and run as they are, on Node 24, the runtime current actions declare. | |
| 39 | | Composite actions | The same. | |
| 40 | | Reusable workflows in the repository (`jobs.<id>.uses: ./.g1t/workflows/build.yml`) | The same: `with:` inputs, `on.workflow_call` outputs, and nesting up to four deep. `./.github/workflows/…` finds the workflow under `.g1t/` after the move. Their jobs read the repository's secrets and variables. | |
| 41 | | `actions/checkout` | Checks out from g1t, with `ref`, `fetch-depth`, `path`, `repository`, `token` and `submodules`. | |
| 42 | | `GITHUB_OUTPUT`, `GITHUB_ENV`, `GITHUB_PATH`, `GITHUB_STATE`, `GITHUB_STEP_SUMMARY` | The same. | |
| 43 | | `::error::`, `::warning::`, `::notice::`, `::group::`, `::add-mask::` | The same: errors and warnings become annotations on the run. | |
| 44 | | `secrets.*`, `vars.*`, `secrets.GITHUB_TOKEN` | The same. `secrets.G1T_TOKEN` is the workspace's own token for the run; `GITHUB_TOKEN` is its alias. | |
| 45 | | `environment:` on a job | The job reads each key's row for that environment, as GitHub's environment secrets work. | |
| 46 | | `actions/upload-artifact`, `actions/download-artifact` | Kept with the run for 14 days, passed between its jobs, and downloadable from the run's page. Up to 60 MB each. | |
| 47 | | `actions/cache`, `actions/cache/restore`, `actions/cache/save` | Kept per repository for 7 days, found by `key` or the newest under a `restore-keys` prefix. Up to 60 MB each. | |
| 48 | |
| 49 | The **Actions** page of a workflow says, under *How this runs on g1t*, |
| 50 | anything in it that runs differently. |
| 51 | |
| 52 | ### Not yet |
| 53 | |
| 54 | - **Windows and macOS runners.** Jobs run on Linux; a job with |
| 55 | `runs-on: windows-latest` or `macos-latest` fails, and says so. |
| 56 | - **Docker** container actions, `services:` containers and `container:`. |
| 57 | - **Reusable workflows from other repositories** (`uses: owner/repo/.github/workflows/x.yml@v1`); ones in the same repository work. |
| 58 | - **The toolkit's own cache.** Actions that cache through GitHub's service |
| 59 | themselves, such as `actions/setup-node` with `cache: npm`, run without |
| 60 | it. Use `actions/cache` for the same effect. |
| 61 | - **Environments' protection rules** (required reviewers, wait timers, |
| 62 | branch limits). A job with `environment:` gets that environment's |
| 63 | [values](/guides/secrets-and-variables/#a-value-per-environment), and runs |
| 64 | without waiting. |
| 65 | |
| 66 | ## The runner |
| 67 | |
| 68 | Jobs run in a fresh sandbox each: Debian with Node 24, Python 3, Go, Rust, |
| 69 | `build-essential`, `git`, `curl`, `jq` and passwordless `sudo`, in GitHub's |
| 70 | layout (`/home/runner/work`, `RUNNER_TEMP`, `RUNNER_TOOL_CACHE`). |
| 71 | `runner.os` is `Linux`. `ubuntu-latest`, `ubuntu-24.04`, `self-hosted` and |
| 72 | other Linux labels all run here. Setup actions such as |
| 73 | `actions/setup-node` and `actions/setup-python` install other versions as |
| 74 | they do on GitHub. |
| 75 | |
| 76 | A job runs for at most 60 minutes, whatever its `timeout-minutes`. |
| 77 | |
| 78 | ## Runs and logs |
| 79 | |
| 80 | Open a repository's **Actions** page, in its sidebar. Pick a workflow to |
| 81 | see its runs, run it by hand if it has `workflow_dispatch`, or turn it off |
| 82 | without touching its file. |
| 83 | |
| 84 | A run's page shows its jobs, each job's steps, and their logs as they are |
| 85 | written. Groups fold, errors and warnings are marked, and secrets are |
| 86 | replaced with `***`. **Cancel**, **Re-run all jobs** and **Re-run failed |
| 87 | jobs** do what they say. |
| 88 | |
| 89 | ## Pull requests |
| 90 | |
| 91 | A pull request's workflows run on each new head: when it is opened, when |
| 92 | a commit is pushed to it, and, for one a g1t agent makes, when the agent |
| 93 | marks it ready, which on g1t is when it first has code. Each head runs |
| 94 | each workflow once. |
| 95 | |
| 96 | A run on a pull request's latest commit is a check on it: |
| 97 | |
| 98 | - While a workflow runs, the pull request waits for it before merging. |
| 99 | - When one fails, merging is refused, as for failed acceptance checks. |
| 100 | Where the repository allows ignoring checks, a member can merge anyway. |
| 101 | - In a repository that merges through the [merge queue](/guides/merge-queue/), |
| 102 | workflows with `on: merge_group` run on each combined state the queue |
| 103 | builds, as on GitHub, and the state lands only if they pass. |
| 104 | - A pull request a **g1t agent** is working on goes back to the agent |
| 105 | when a workflow fails. The agent reads the run and its logs with the |
| 106 | same tools you have, fixes the cause, and pushes; the workflows run |
| 107 | again. |
| 108 | |
| 109 | ## Secrets and variables |
| 110 | |
| 111 | Secrets are read as `${{ secrets.KEY }}` and config as `${{ vars.KEY }}`, |
| 112 | from the rows under **Settings → Secrets and variables** that are |
| 113 | available to Workflows. A job with `environment: production` reads each |
| 114 | key's Production row; other jobs read the rows for all environments. See |
| 115 | [Secrets and variables](/guides/secrets-and-variables/) for how rows, |
| 116 | environments and the workspace's rows work. |
| 117 | |
| 118 | Every trusted job also gets `${{ secrets.G1T_TOKEN }}`, the workspace's own |
| 119 | token for the run, with `GITHUB_TOKEN` as its alias. Pull requests from |
| 120 | people outside the workspace run without secrets, and with an empty |
| 121 | token. |
| 122 | |
| 123 | ## Who may run workflows |
| 124 | |
| 125 | Workflows run in every workspace that can use g1t's agents: one with its |
| 126 | own [model provider](/guides/models/) connected, or one on |
| 127 | [the free allowance](/guides/usage-and-billing/#the-free-allowance) while |
| 128 | it lasts. They are free while g1t is being built out. Elsewhere a run is |
| 129 | recorded with its jobs failed and the reason, and the Actions page says so |
| 130 | before the first run. |
| 131 | |
| 132 | ## From the API |
| 133 | |
| 134 | The routes are GitHub's, so scripts written for GitHub's API mostly work |
| 135 | with `https://api.g1t.sh` in place of `https://api.github.com`. |
| 136 | |
| 137 | | Tool | Route | |
| 138 | | --- | --- | |
| 139 | | `list_workflows` | `GET /repos/{owner}/{repo}/actions/workflows` | |
| 140 | | `list_workflow_runs` | `GET /repos/{owner}/{repo}/actions/runs`, with `workflow`, `branch`, `event`, `pull`, `head_sha` | |
| 141 | | `get_workflow_run` | `GET /repos/{owner}/{repo}/actions/runs/{id}` | |
| 142 | | `get_job_logs` | `GET /repos/{owner}/{repo}/actions/jobs/{job}/logs?after=` | |
| 143 | | `dispatch_workflow` | `POST /repos/{owner}/{repo}/actions/workflows/{workflow}/dispatches` with `ref` and `inputs` | |
| 144 | | `cancel_workflow_run` | `POST /repos/{owner}/{repo}/actions/runs/{id}/cancel` | |
| 145 | | `rerun_workflow_run` | `POST …/runs/{id}/rerun`, or `…/rerun-failed-jobs` | |
| 146 | | `update_workflow` | `PUT …/workflows/{workflow}/enable` and `…/disable` | |
| 147 | | `list_actions_secrets`, `set_actions_secret`, `delete_actions_secret` | `GET`, `PUT` and `DELETE /repos/{owner}/{repo}/actions/secrets/{name}` | |
| 148 | | `list_actions_variables`, `set_actions_variable`, `delete_actions_variable` | `GET` and `POST /repos/{owner}/{repo}/actions/variables`, `PATCH` and `DELETE …/variables/{name}` | |
| 149 | |
| 150 | Workspace secrets and variables are under |
| 151 | `/workspaces/{workspace}/actions/secrets` and `…/variables`. The fields |
| 152 | g1t adds (environments, who reads a row, linked repositories) are in |
| 153 | [Secrets and variables](/guides/secrets-and-variables/#from-the-api). |
| 154 | |
| 155 | ```sh |
| 156 | curl -X POST https://api.g1t.sh/repos/acme/web/actions/workflows/ci.yml/dispatches \ |
| 157 | -H "Authorization: Bearer $G1T_TOKEN" -H "Content-Type: application/json" \ |
| 158 | -d '{"ref": "main", "inputs": {"environment": "staging"}}' |
| 159 | ``` |
| 160 | |