> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions

> Run supported workflows in the GitHub twin and inspect jobs, logs, and artifacts

The `github` twin provides repositories, pull requests, and GitHub Actions in one environment. Its API and browser interface share the same repository state. You do not need a separate Actions twin.

## Choose an execution mode

| Mode | Behavior |
| - | - |
| `simulated` | The default. Actions APIs and UI use seeded state and configured results. Workflow commands do not execute. |
| `execute` | Runs supported workflows with `act` in disposable Cloud Build workers. Jobs, logs, and artifact bytes come from actual execution. |

A successful seeded run does not prove that workflow commands ran. In simulation mode, a dispatched run needs configured execution fixtures to progress; without them, it can remain queued. Starting the twin locally does not start a workflow runner.

## Start a GitHub twin with execution enabled

In **Twin Runs**, select **GitHub**, then enable **Run GitHub Actions workflows**. This option makes the environment private. It is also available when starting permanent twins from a Scenario; changing the execution mode reprovisions that environment.

You can also [provision through the API](https://docs.argalabs.com/api-reference/post-provision-twins.md):

```bash theme={null}
curl --fail-with-body https://api.argalabs.com/twin-runs \
  -H "Authorization: Bearer $ARGA_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "twins": ["github"],
    "github_actions_mode": "execute",
    "public": false,
    "ttl_minutes": 60
  }'
```

Poll [Twin Run status](https://docs.argalabs.com/api-reference/get-get-twin-provision-status.md) until `status` is `ready`. Check that `github_actions_mode` is `execute` before dispatching a workflow.

With a CLI release that includes `--execute-github-actions`, use:

```bash theme={null}
arga twin-runs create --twins github --execute-github-actions --ttl 60 --wait --json
```

The flag requests private access automatically. If `arga twin-runs create --help` does not list it, use the API request above. The older `github_actions` twin name remains a compatibility alias for existing environments and clients; use `github` for new environments.

For Arga's [MCP tools](https://docs.argalabs.com/mcp-tools.md), call `create_twin_run` with `twins: "github"` and `github_actions_mode: "execute"`. This also requests private access and enforces the same eligibility checks.

## Add and dispatch a workflow

Seed a repository through a [Scenario](https://docs.argalabs.com/features/custom-scenarios.md), or create one through the twin's GitHub API. Add this file as `.github/workflows/smoke.yml` on `main` using Git push or the Contents API:

```yaml theme={null}
name: Runner smoke
'on': workflow_dispatch
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Write proof
        run: |
          printf 'actions-worked\n' > proof.txt
          echo RUNNER_EXECUTED
      - uses: actions/upload-artifact@v4
        with:
          name: runner-proof
          path: proof.txt
```

Use these values from the ready Twin Run response:

| Local variable | Response field |
| - | - |
| `GITHUB_API_BASE_URL` | `twins.github.env_vars.GITHUB_API_BASE_URL`, also returned as `twins.github.base_url` |
| `GITHUB_TOKEN` | `twins.github.env_vars.GITHUB_TOKEN` |
| `ARGA_PROXY_TOKEN` | `proxy_token` |

Private environments require both the Arga proxy credential and the twin's GitHub credential. The examples send the proxy token in a cookie and the GitHub token in the authorization header:

```bash theme={null}
curl --fail-with-body \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  --cookie "arga_env_proxy_token=$ARGA_PROXY_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"ref":"main"}' \
  "$GITHUB_API_BASE_URL/repos/OWNER/REPO/actions/workflows/smoke.yml/dispatches"
```

Replace `OWNER` and `REPO` with your twin repository. A successful dispatch returns HTTP `204`. Poll the run list for its ID:

```bash theme={null}
curl --fail-with-body \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  --cookie "arga_env_proxy_token=$ARGA_PROXY_TOKEN" \
  "$GITHUB_API_BASE_URL/repos/OWNER/REPO/actions/runs"
```

## Inspect the result

Open GitHub from the Twin Run dashboard, select your repository, and choose **Actions** to inspect runs, jobs, logs, and artifacts. Browser write and download controls depend on the current GitHub principal's permissions; proxy access alone does not grant GitHub permissions.

The same state is available through the native APIs. Use the authentication headers and cookie from the examples above:

| Operation | Method and path |
| - | - |
| Read a run | `GET /repos/OWNER/REPO/actions/runs/RUN_ID` |
| List jobs and steps | `GET /repos/OWNER/REPO/actions/runs/RUN_ID/jobs` |
| Download run logs | `GET /repos/OWNER/REPO/actions/runs/RUN_ID/logs` |
| List artifacts | `GET /repos/OWNER/REPO/actions/runs/RUN_ID/artifacts` |
| Download an artifact ZIP | `GET /repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID/zip` |
| Rerun the complete workflow | `POST /repos/OWNER/REPO/actions/runs/RUN_ID/rerun` |
| Cancel a run | `POST /repos/OWNER/REPO/actions/runs/RUN_ID/cancel` |

For the smoke workflow, verify the run and job succeed, the logs contain `RUNNER_EXECUTED`, and the artifact ZIP contains `proof.txt` with `actions-worked` followed by a newline. To test failure, dispatch a workflow containing `run: exit 7` and verify its job and run report failure.

Execution captures the workflow and repository commit at admission. A full rerun reuses that captured source even if the branch has moved. Resetting or deleting the environment stops its outstanding execution.

## Supported workflows and limits

Real execution supports `workflow_dispatch` and branch `push` events, shell commands, job dependencies through `needs`, job and step outputs, supported `if` expressions, and boolean step-level `continue-on-error`.

Approved actions are `actions/checkout@v4`, `actions/setup-node@v4`, `actions/setup-python@v5`, `actions/upload-artifact@v4`, and `actions/download-artifact@v4`. These aliases resolve to pinned revisions. Checkout uses the captured repository and commit without persisting credentials.

* Each workflow supports up to 8 jobs and 100 steps in total. Jobs run serially within an attempt.
* One execution can consume compute per environment at a time. There is no queue for additional workflow admissions.
* The default deadline is 600 seconds. The deployment controls the deadline, up to 900 seconds, and the execution quota; the default quota is 100 attempts per account per UTC day.
* `ubuntu-latest`, `ubuntu-22.04`, and `ubuntu-24.04` select the same minimal pinned Debian runner image. They do not provide GitHub's hosted Ubuntu tool inventory.
* Matrices, reusable workflows, local or Docker actions, containers/services, caches, deployment approvals, OIDC, Windows/macOS runners, and selective failed-job reruns are unsupported. Unsupported execution requests fail visibly.
* Jobs receive no real GitHub token, user secrets, cloud credentials, or Docker socket. Calls from a job to GitHub do not route back into its originating twin; the runner has no scoped API bridge to that twin.

GitHub-shaped APIs for secrets, variables, caches, and other modeled resources do not imply that the execution worker supports those features. Use this preview for supported small workflows rather than assuming complete GitHub Actions parity.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.