# GitHub Actions

> Use RunEnv safely in GitHub Actions workflows.

Canonical HTML: /en/docs/client-interfaces/github-actions
Canonical Markdown: /agent-docs/client-interfaces/github-actions.md
Audience: developer, operator
Agent safety: context-only

---

Use the RunEnv GitHub Action or CLI with a least-privilege service token stored in GitHub Actions secrets. Never commit a token or resolved secret value to the repository, workflow logs, artifacts, or job summary.

## Quickstart

```yaml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Jambo-company/runenv-action@v1
        with:
          token: ${{ secrets.RUNENV_TOKEN }}
          project: my-api
          environment: production
          command: npm run deploy
```

## Branch and environment policy

Bind a separate RunEnv environment to each deployment boundary. For example, use `staging` on protected staging branches and `production` only on protected production branches. Give each workflow token only the project and environment permissions it needs.

## Env files and Docker

Prefer process-level injection during a workflow step. Avoid exporting values into a tracked `.env` file or a Docker image layer. If a build tool requires a file, create it in the job workspace only for that step, prevent it from being uploaded as an artifact, and delete it afterward.

```yaml
- name: Build with runtime injection
  run: runenv run -- npm run build
  env:
    RUNENV_TOKEN: ${{ secrets.RUNENV_TOKEN }}
```

For Docker, use BuildKit secrets or a runtime container environment; do not pass secret values through `ARG`, `ENV`, image history, or build logs.

## Self-hosted runners

Self-hosted runners must use the HTTPS URL of your RunEnv deployment and an identity scoped to the runner's job. Do not use a human user token as a long-lived runner credential. Rotate the service token and remove it immediately when a runner is retired or compromised.

## Inputs and troubleshooting

Typical configuration needs a token, project, environment, and command. Check the action version and its README for the complete supported input contract. If a job cannot retrieve configuration, verify the token scope, selected project/environment, and server URL without printing credential material.