Skip to main content

Install and configure 1Password

Configure a 1Password service account token, check vault access, and run a job that verifies a secret file was injected.

Prerequisites​

RequirementHow to verify
A 1Password service account tokenStarts with ops_... — create one in 1Password
Vault accessThe service account must have read access to every vault referenced by your workflow
Loom CLI availableRun loom version to confirm

Loom uses the 1Password Go SDK for secret resolution. No op CLI installation is required.

Step 1: Export your service account token​

Set the token in your shell before running any Loom command:

export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

Loom reads this variable from its runtime environment. Keep the token out of workflow files and avoid printing the host environment.

tip

Store this export in a local .env file (excluded from version control) and source it at the start of each session. This avoids retyping the token every time.

Step 2: Verify connectivity​

Confirm the token can reach 1Password by listing your accessible vaults:

loom secrets op vault list

Expected output:

name=Engineering id=vlt_abc123
name=Platform    id=vlt_def456

If the command returns an error, check:

  • The token value is correct and not truncated.
  • Your network can reach the 1Password API.
  • The service account has at least one vault assigned.

Step 3: Validate with a workflow​

Add an op:// secret to a job​

Save this as .loom/workflow.yml, replacing the reference with an existing item and field your service account can read.

version: v1
stages: [ci]

check-secret:
  stage: ci
  target: linux
  secrets:
    DEPLOY_TOKEN:
      ref: op://Engineering/deploy/token
  script:
    - test -r "$DEPLOY_TOKEN" && test -s "$DEPLOY_TOKEN"
    - echo "Secret file is readable and non-empty"

Check and run​

loom check validates workflow structure; it does not contact 1Password. The run below resolves the reference and checks the injected file.

loom check
loom run --local --workflow .loom/workflow.yml

A successful check prints Secret file is readable and non-empty and the run exits with status 0. If resolution fails, Loom returns one of the error codes documented in the overview.

Loom redacts exact matches for declared secret values in console/event output, receipt stdout/stderr, output-bearing errors, and provider lifecycle messages. Transformed values and raw declared artifact contents are not covered; inspect and sanitize evidence before sharing it.

CI/CD configuration​

In CI environments, set OP_SERVICE_ACCOUNT_TOKEN as a masked/protected variable in your runner configuration:

CI systemWhere to set
GitLab CISettings > CI/CD > Variables (masked, protected)
GitHub ActionsRepository or environment secrets
OtherInject as an environment variable in the job execution shell

Make sure the CI job exports the token into the process that starts Loom. Loom uses the same environment variable locally and in CI.

Troubleshooting​

SymptomLikely causeFix
SECRETS_PROVIDER_UNAVAILABLEToken missing, empty, or rejected by 1Password APIExport a valid OP_SERVICE_ACCOUNT_TOKEN
SECRETS_REF_NOT_FOUNDVault, item, or field does not existVerify the ref exists in 1Password; check vault access for the service account
SECRETS_REF_INVALIDMalformed op:// URICheck for missing segments or illegal characters (no query/fragment allowed)
vault list returns nothingToken lacks vault permissionsUpdate the service account's vault access in 1Password
Network timeoutFirewall or proxy blocking 1Password APIEnsure outbound HTTPS to my.1password.com is allowed

Next steps​