docs/cli-docs/ci.md

sidebar_position

sidebar_position
4

Using gt in CI

In CI there is nobody to log in, answer a prompt or confirm a deletion. Give gt a token and an instance through the environment, select the repository explicitly, and turn prompts off.

Environment

Variable	Description
GITEA_TOKEN	Access token, used instead of stored credentials
GITEA_CLI_HOST or GITEA_INSTANCE_URL	URL of the instance the token belongs to
GITEA_CLI_REPO	Repository as OWNER/REPO or URL, like --repo
GITEA_INSTANCE_INSECURE	With GITEA_TOKEN, skip TLS verification when true
GITEA_INSTANCE_SSH_HOST	With GITEA_TOKEN, the SSH host that identifies the instance's remotes

gt never stores a token it reads from GITEA_TOKEN, so nothing has to be cleaned up after the job. Keep the token in your CI system's secrets; never write it into config.yml or hosts.yml. Create it as described in Logging in, with only the scopes the job needs.

gt help environment lists every variable gt reads.

Prompts and confirmations

--no-input disables prompts and the editor and browser that some commands open on their own. A command that would need to ask for something fails instead, with exit code 2. Commands that change or delete something ask for confirmation; --yes (-y) gives it in advance:

gt pr merge 123 --repo owner/repository --rebase --yes --no-input

gt auth login --oauth needs a browser and does not work in CI. To store a token on a machine that runs jobs, pipe it in instead:

gt auth login --host https://gitea.example.com --with-token --credential-store file < token.txt

Gitea Actions

Gitea does not allow secret names starting with GITEA_, so store the token under another name, such as GT_TOKEN, and pass it to gt as GITEA_TOKEN:

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      GITEA_TOKEN: ${{ secrets.GT_TOKEN }}
      GITEA_CLI_HOST: ${{ gitea.server_url }}
      GITEA_CLI_REPO: ${{ gitea.repository }}
    steps:
      - name: install gt
        run: curl -fsSL https://gitea.com/gitea/cli/raw/branch/main/scripts/install.sh | sh
      - name: deploy to staging
        run: gt workflow run deploy.yml --ref main --field env=staging --field version=1.2.3 --no-input

Workflows and runs

gt workflow list --no-input --json
gt workflow view deploy.yml --no-input --json
gt workflow run deploy.yml --ref main --field env=staging --field version=1.2.3 --no-input
gt workflow disable deploy.yml --yes --no-input
gt workflow enable deploy.yml --no-input

gt workflow run dispatches a workflow, which needs a workflow_dispatch trigger. To wait for the run, add --follow, or find it with gt run list and watch it:

gt run watch RUN_ID --timeout 10m --no-input

Both fail when the run completes without success, so the job fails with it.

gt pr checks waits for the checks of a pull request with --watch, and exits with 8 while checks are still pending:

gt pr checks 13 --watch && gt pr merge 13 --yes --no-input

See Output and scripting for reading the results of a command, and for the exit codes.