Skip to content

CI and GitHub Action ​

A CI job uses a service account, created in the web app under Settings → Agents & automation → Agents & CI as kind "Service (CI)", and its token. A service account is not an agent: its scope and expiry are the approval, and it is not asked per read.

Put the whole gsm_… token in the secret store of your CI and hand it to the job as the environment variable GESLAR_SERVICE_TOKEN:

yaml
# GitHub Actions: the token goes in `secrets`, never in `vars`, and never as an input of a step
- run: npm install -g @geslar/cli@<exact version> --ignore-scripts
- run: geslar run -e DB_PASSWORD=geslar://CI/Database/password -- ./deploy.sh
  env:
    GESLAR_SERVICE_TOKEN: ${{ secrets.GESLAR_SERVICE_TOKEN }}

With a service account a Vault is given by its name (CI above is the name of a Vault): the keywords personal, osobno, family, company and work are not resolved (a Vault that is itself named like that is found by its name; otherwise it is an error).

What happens ​

  • read, run, inject, item list and whoami / status use the token when it is set and no --agent / GESLAR_AGENT is given. No login, no unlock, no terminal, no prompt: the session lives in memory only, and nothing is written to disk or to a keychain (it works in a container with neither). --unlock makes no sense with a token and is refused.
  • Only a service account's token works from the environment. If the server says the token belongs to an agent, the CLI stops before it asks for any key; agents use geslar agent add on a machine of their own.
  • The child process of geslar run never receives the token or any other GESLAR_* credential, and the token is masked in the child's output. The token is in no message or error either.
  • The scope and the expiry of the account are the approval: there is no per-read approval for a service account.
  • If the server refuses the token (it is unknown, revoked or expired; the server does not say which), geslar exits with code 2 and says exactly that: create a new service account in the browser and update the secret. An agent profile gets a different message, because it is fixed differently: geslar agent add again.

Advice ​

  • One service account per repository, read-only, with the shortest expiry that suits you and a rotation date.
  • One geslar run per job rather than one per step: every start exchanges the token once, and the server limits exchanges per hour and per address.
  • A CI environment with protection for production secrets.
  • Never run it for pull requests from forks. GitHub does not give them your secrets, and pull_request_target with code from the pull request must not be used.

Honest limit: while geslar runs, the token is in its own process environment (on Linux, /proc/<pid>/environ is readable by the same user); it is not passed on to anything it starts.

GitHub Action ​

geslar-eu/secrets-action loads secrets into a workflow job, masked, using a service account token.

yaml
permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: geslar-eu/secrets-action@<full-40-character-commit-sha>   # pin by SHA
        with:
          version: 1.0.0            # exact @geslar/cli version, required
          secrets: |
            DB_PASSWORD=geslar://Production/database/password
            API_TOKEN=geslar://Production/payments/token
        env:
          GESLAR_SERVICE_TOKEN: ${{ secrets.GESLAR_SERVICE_TOKEN }}

      - run: ./deploy.sh            # DB_PASSWORD and API_TOKEN are in the environment from here on
  • Pin the action by full commit SHA, and pin the CLI with version. Both are code that runs next to your token; neither should change unless you change the line.
  • version is required and must be an exact @geslar/cli version: no default, no range, no tag (latest and next are refused). It has to be 1.0.0 or newer, because earlier versions do not know service tokens.
  • The token is deliberately not an input, because inputs appear in the invocation log. Pass it as the env: of the step, from a repository or environment secret.
  • The action masks each value the moment it is resolved and exports to GITHUB_ENV only after every reference resolved: one failure means nothing is exported.
  • Values written to GITHUB_ENV are visible to every later step of the job, including third-party actions. If one step needs a secret, prefer geslar run -- your-command in that step.
  • The action refuses fork pull requests and pull_request_target.

The full list of inputs, the refused variable names and the failure behaviour are in the action's README.