1password

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1Password

Overview

概述

This skill provides comprehensive guidance for working with 1Password's secrets management ecosystem. It covers the

op

CLI for local development, service accounts for automation, Developer Environments for project secrets, and Kubernetes integrations including the native 1Password Operator and External Secrets Operator.

本指南提供了使用1Password密钥管理生态系统的全面指导，涵盖用于本地开发的

op

CLI、用于自动化的服务账号、用于项目密钥的开发者环境，以及包括原生1Password Operator和External Secrets Operator在内的Kubernetes集成。

Quick Reference

快速参考

Command Structure

命令结构

1Password CLI uses a noun-verb structure:

op <noun> <verb> [flags]

bash

undefined

1Password CLI采用名词-动词结构：

op <noun> <verb> [flags]

bash

undefined

Authentication

身份验证

op signin # Sign in to account op signout # Sign out op whoami # Show signed-in account info

op signin # 登录账号 op signout # 登出 op whoami # 显示当前登录账号信息

Secret retrieval

密钥检索

op read "op://vault/item/field" # Read single secret op run -- <command> # Inject secrets as env vars op inject -i template.env -o .env # Inject secrets into file

op read "op://vault/item/field" # 读取单个密钥 op run -- <command> # 将密钥作为环境变量注入 op inject -i template.env -o .env # 将密钥注入文件

Item management

条目管理

op item list # List all items op item get <item> # Get item details op item create --category login # Create new item op item edit <item> field=value # Edit item op item delete <item> # Delete item

op item list # 列出所有条目 op item get <item> # 获取条目详情 op item create --category login # 创建新条目 op item edit <item> field=value # 编辑条目 op item delete <item> # 删除条目

Vault management

保管库管理

op vault list # List vaults op vault get <vault> # Get vault info op vault create <name> # Create vault

op vault list # 列出保管库 op vault get <vault> # 获取保管库信息 op vault create <name> # 创建保管库

Document management

文档管理

op document list # List documents op document get <document> # Download document op document create <file> --vault <vault> # Upload document

undefined

op document list # 列出文档 op document get <document> # 下载文档 op document create <file> --vault <vault> # 上传文档

undefined

Workflow Decision Tree

工作流决策树

What do you need to do?
├── Retrieve a secret for local development?
│   └── Use: op read, op run, or op inject
├── Manage project environment variables?
│   └── See: Developer Environments (below)
├── Manage items/vaults in 1Password?
│   └── Use: op item, op vault, op document commands
├── Automate secrets in CI/CD?
│   └── Use: Service Accounts with OP_SERVICE_ACCOUNT_TOKEN
├── Sync secrets to Kubernetes?
│   ├── Using External Secrets Operator?
│   │   └── See: External Secrets Operator Integration
│   └── Using native 1Password Operator?
│       └── See: 1Password Kubernetes Operator
└── Configure shell plugins for CLI tools?
    └── Use: op plugin commands

你需要执行什么操作？
├── 为本地开发检索密钥？
│   └── 使用：op read、op run 或 op inject
├── 管理项目环境变量？
│   └── 查看：开发者环境（下方）
├── 在1Password中管理条目/保管库？
│   └── 使用：op item、op vault、op document 命令
├── 在CI/CD中实现密钥自动化？
│   └── 使用：带有OP_SERVICE_ACCOUNT_TOKEN的服务账号
├── 将密钥同步到Kubernetes？
│   ├── 使用External Secrets Operator？
│   │   └── 查看：External Secrets Operator集成
│   └── 使用原生1Password Operator？
│       └── 查看：1Password Kubernetes Operator
└── 为CLI工具配置Shell插件？
    └── 使用：op plugin 命令

Developer Environments

开发者环境

Developer Environments provide a dedicated location to store, organize, and manage project secrets as environment variables. CLI tools are available in both TypeScript/Bun and Python SDK variants.

开发者环境提供了一个专用位置，用于存储、组织和管理作为环境变量的项目密钥。CLI工具提供TypeScript/Bun和Python SDK两种版本。

Feature Overview

功能概述

Feature	GUI	TypeScript CLI	Python SDK CLI
Create environment	Yes	`bun run create`	`uv run op-env-create`
Update environment	Yes	`bun run update`	`uv run op-env-update`
Delete environment	Yes	`bun run delete`	`uv run op-env-delete`
Show environment	Yes	`bun run show`	`uv run op-env-show`
List environments	Yes	`bun run list`	`uv run op-env-list`
Export to .env	Yes	`bun run export`	`uv run op-env-export`
Mount .env file	Yes (beta)	No	No

功能	GUI	TypeScript CLI	Python SDK CLI
创建环境	是	`bun run create`	`uv run op-env-create`
更新环境	是	`bun run update`	`uv run op-env-update`
删除环境	是	`bun run delete`	`uv run op-env-delete`
查看环境	是	`bun run show`	`uv run op-env-show`
列出环境	是	`bun run list`	`uv run op-env-list`
导出到.env	是	`bun run export`	`uv run op-env-export`
挂载.env文件	是（测试版）	否	否

CLI Tools Setup (TypeScript)

CLI工具设置（TypeScript）

Tools are written in TypeScript and require Bun runtime:

bash

undefined

工具基于TypeScript编写，需要Bun运行时：

bash

undefined

Navigate to tools directory

导航到工具目录

cd tools

Run any tool with bun

使用bun运行任意工具

bun run src/op-env-create.ts --help bun run src/op-env-list.ts --help

Or use npm scripts

或使用npm脚本

bun run create -- --help bun run list -- --help

undefined

bun run create -- --help bun run list -- --help

undefined

CLI Tools Setup (Python SDK)

CLI工具设置（Python SDK）

Python tools use the official

onepassword-sdk

package and require uv:

bash

undefined

Python工具使用官方

onepassword-sdk

包，需要uv：

bash

undefined

Navigate to tools-python directory

导航到tools-python目录

cd tools-python

Install dependencies

安装依赖

uv sync

Run any tool

运行任意工具

uv run op-env-create --help uv run op-env-list --help


**Requirements:** Python 3.9+, `OP_SERVICE_ACCOUNT_TOKEN` environment variable.

uv run op-env-create --help uv run op-env-list --help


**要求：** Python 3.9+、`OP_SERVICE_ACCOUNT_TOKEN`环境变量。

When to Use SDK vs CLI

SDK与CLI的使用场景对比

Use Case	Recommended	Why
Python applications (FastAPI, Django)	Python SDK	Native async, no subprocess overhead
Shell scripts, CI/CD pipelines	TypeScript CLI or `op` CLI	Direct CLI integration
Batch secret resolution	Python SDK	`resolve_all()` for efficiency
Tag-based filtering	TypeScript CLI	SDK lacks tag filter support
Interactive local development	Either	Both have identical interfaces

使用场景	推荐方案	原因
Python应用（FastAPI、Django）	Python SDK	原生异步，无子进程开销
Shell脚本、CI/CD流水线	TypeScript CLI或 `op` CLI	直接CLI集成
批量密钥解析	Python SDK	`resolve_all()` 提升效率
基于标签的过滤	TypeScript CLI	SDK缺乏标签过滤支持
交互式本地开发	两者均可	界面完全一致

SecretsManager (Python SDK)

SecretsManager（Python SDK）

For Python applications that need runtime secret resolution:

python

from op_env.secrets_manager import SecretsManager

async def main():
    sm = await SecretsManager.create()

    # Single secret (with caching)
    api_key = await sm.get("op://Production/API/key")

    # Batch resolve
    secrets = await sm.get_many([
        "op://Production/DB/password",
        "op://Production/DB/host",
    ])

    # Load all vars from an environment item
    env = await sm.resolve_environment("my-app-prod", "Production")

See

references/python-sdk.md

for full SDK reference and integration patterns.

适用于需要运行时密钥解析的Python应用：

python

from op_env.secrets_manager import SecretsManager

async def main():
    sm = await SecretsManager.create()

    # 单个密钥（带缓存）
    api_key = await sm.get("op://Production/API/key")

    # 批量解析
    secrets = await sm.get_many([
        "op://Production/DB/password",
        "op://Production/DB/host",
    ])

    # 从环境条目加载所有变量
    env = await sm.resolve_environment("my-app-prod", "Production")

完整SDK参考和集成模式请查看

references/python-sdk.md

。

Environment Workflow

环境工作流

1. Create Environment

1. 创建环境

bash

undefined

bash

undefined

From inline variables

从内联变量创建

bun run src/op-env-create.ts my-app-dev Personal
API_KEY=secret
DB_HOST=localhost
DB_PORT=5432

From .env file

从.env文件创建

bun run src/op-env-create.ts my-app-prod Production --from-file .env.prod

Combine file + inline (inline overrides file)

组合文件+内联变量（内联变量覆盖文件内容）

bun run src/op-env-create.ts azure-config Shared --from-file .env EXTRA_KEY=value

With custom tags

带自定义标签

bun run src/op-env-create.ts secrets DevOps --tags "env,production,api" KEY=value

undefined

bun run src/op-env-create.ts secrets DevOps --tags "env,production,api" KEY=value

undefined

2. List Environments

2. 列出环境

bash

undefined

bash

undefined

List all environments (tagged with 'environment')

列出所有环境（带'environment'标签）

bun run src/op-env-list.ts

Filter by vault

按保管库过滤

bun run src/op-env-list.ts --vault Personal

Filter by tags

按标签过滤

bun run src/op-env-list.ts --tags "production"

JSON output

JSON格式输出

bun run src/op-env-list.ts --json

undefined

bun run src/op-env-list.ts --json

undefined

3. Show Environment Details

3. 查看环境详情

bash

undefined

bash

undefined

Show with masked values (default)

查看（默认掩码显示值）

bun run src/op-env-show.ts my-app-dev Personal

Show with revealed values

查看（显示真实值）

bun run src/op-env-show.ts my-app-dev Personal --reveal

JSON output

JSON格式输出

bun run src/op-env-show.ts my-app-dev Personal --json

Show only variable names

仅显示变量名

bun run src/op-env-show.ts my-app-dev Personal --keys

undefined

bun run src/op-env-show.ts my-app-dev Personal --keys

undefined

4. Update Environment

4. 更新环境

bash

undefined

bash

undefined

Update/add single variable

更新/添加单个变量

bun run src/op-env-update.ts my-app-dev Personal API_KEY=new-key

Merge from .env file

从.env文件合并更新

bun run src/op-env-update.ts my-app-dev Personal --from-file .env.local

Remove variables

删除变量

bun run src/op-env-update.ts my-app-dev Personal --remove OLD_KEY,DEPRECATED

Update and remove in one command

同时更新和删除变量

bun run src/op-env-update.ts my-app-dev Personal NEW_KEY=value --remove OLD_KEY

undefined

bun run src/op-env-update.ts my-app-dev Personal NEW_KEY=value --remove OLD_KEY

undefined

5. Export Environment

5. 导出环境

bash

undefined

bash

undefined

Export to .env file (standard format)

导出到.env文件（标准格式）

bun run src/op-env-export.ts my-app-dev Personal > .env

Docker-compatible format (quoted values)

Docker兼容格式（带引号的值）

bun run src/op-env-export.ts my-app-dev Personal --format docker > .env

op:// references template (for op run/inject)

op://引用模板（用于op run/inject）

bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

JSON format

JSON格式

bun run src/op-env-export.ts my-app-dev Personal --format json

Add prefix to all variables

为所有变量添加前缀

bun run src/op-env-export.ts azure-config Shared --prefix AZURE_ > .env

undefined

bun run src/op-env-export.ts azure-config Shared --prefix AZURE_ > .env

undefined

6. Delete Environment

6. 删除环境

bash

undefined

bash

undefined

Interactive deletion (asks for confirmation)

交互式删除（需确认）

bun run src/op-env-delete.ts my-app-dev Personal

Force delete without confirmation

强制删除（无需确认）

bun run src/op-env-delete.ts my-app-dev Personal --force

Archive instead of permanent delete

归档而非永久删除

bun run src/op-env-delete.ts my-app-dev Personal --archive

undefined

bun run src/op-env-delete.ts my-app-dev Personal --archive

undefined

Environment Secret Reference

环境密钥引用

Access individual variables using the secret reference format:

op://<vault>/<environment>/variables/<key>

Example:

bash

undefined

使用以下密钥引用格式访问单个变量：

op://<vault>/<environment>/variables/<key>

示例：

bash

undefined

Read single variable

读取单个变量

op read "op://Personal/my-app-dev/variables/API_KEY"

Use in template file (.env.tpl)

在模板文件中使用（.env.tpl）

API_KEY=op://Personal/my-app-dev/variables/API_KEY DB_HOST=op://Personal/my-app-dev/variables/DB_HOST

undefined

API_KEY=op://Personal/my-app-dev/variables/API_KEY DB_HOST=op://Personal/my-app-dev/variables/DB_HOST

undefined

Integration Patterns

集成模式

With op run (recommended)

与op run配合使用（推荐）

bash

undefined

bash

undefined

1. Export environment as op:// template

1. 将环境导出为op://模板

bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

2. Run command with injected secrets

2. 运行命令并注入密钥

op run --env-file .env.tpl -- ./deploy.sh op run --env-file .env.tpl -- docker compose up op run --env-file .env.tpl -- npm start op run --env-file .env.tpl -- python app.py

undefined

op run --env-file .env.tpl -- ./deploy.sh op run --env-file .env.tpl -- docker compose up op run --env-file .env.tpl -- npm start op run --env-file .env.tpl -- python app.py

undefined

With op inject

与op inject配合使用

bash

undefined

bash

undefined

1. Create template with op:// references

1. 创建包含op://引用的模板

bun run src/op-env-export.ts my-app-dev Personal --format op-refs > config.tpl

2. Inject secrets into file

2. 将密钥注入文件

op inject -i config.tpl -o .env

3. Use the generated .env file

3. 使用生成的.env文件

source .env && ./app

undefined

source .env && ./app

undefined

With Docker Compose

与Docker Compose配合使用

bash

undefined

bash

undefined

1. Export environment

1. 导出环境

bun run src/op-env-export.ts my-app-dev Personal --format op-refs > .env.tpl

2. Run docker compose with secrets

2. 运行Docker Compose并加载密钥

op run --env-file .env.tpl -- docker compose up -d

undefined

op run --env-file .env.tpl -- docker compose up -d

undefined

In CI/CD (GitHub Actions)

在CI/CD中使用（GitHub Actions）

yaml

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1

      - name: Load secrets
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          API_KEY: op://CI-CD/my-app-prod/variables/API_KEY
          DB_PASSWORD: op://CI-CD/my-app-prod/variables/DB_PASSWORD

      - name: Deploy
        run: ./deploy.sh

yaml

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1

      - name: Load secrets
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          API_KEY: op://CI-CD/my-app-prod/variables/API_KEY
          DB_PASSWORD: op://CI-CD/my-app-prod/variables/DB_PASSWORD

      - name: Deploy
        run: ./deploy.sh

Current Environments (Barbosa Account)

当前环境（Barbosa账号）

Environment	Vault	Description
hypera-azure-rg-hypera-cafehyna-web-dev	-	Azure RG - Cafehyna Web Dev
hypera-azure-devops-team-az-cli-pim	-	Azure DevOps Team - CLI PIM
devops-team-pim	-	DevOps Team PIM credentials
hypera-github-python-devops	-	GitHub - Python DevOps
hypera-azure-rg-hypera-cafehyna-web	-	Azure RG - Cafehyna Web Prod
repos-github-zsh	-	GitHub - ZSH repository
hypera	-	General Hypera infrastructure
Azure OpenAI-finops	-	Azure OpenAI FinOps config

See

references/environments/inventory.md

for detailed documentation.

环境	保管库	描述
hypera-azure-rg-hypera-cafehyna-web-dev	-	Azure资源组 - Cafehyna Web开发环境
hypera-azure-devops-team-az-cli-pim	-	Azure DevOps团队 - CLI PIM
devops-team-pim	-	DevOps团队PIM凭据
hypera-github-python-devops	-	GitHub - Python DevOps
hypera-azure-rg-hypera-cafehyna-web	-	Azure资源组 - Cafehyna Web生产环境
repos-github-zsh	-	GitHub - ZSH仓库
hypera	-	Hypera通用基础设施
Azure OpenAI-finops	-	Azure OpenAI FinOps配置

详细文档请查看

references/environments/inventory.md

。

Secret Retrieval

密钥检索

Secret Reference Format

密钥引用格式

The standard format for referencing secrets:

op://<vault>/<item>/<field>

Examples:

```
op://Development/AWS/access_key_id
```
```
op://Production/Database/password
```
```
op://Shared/API Keys/github_token
```

引用密钥的标准格式：

op://<vault>/<item>/<field>

示例：

```
op://Development/AWS/access_key_id
```
```
op://Production/Database/password
```
```
op://Shared/API Keys/github_token
```

Reading Secrets Directly

直接读取密钥

bash

undefined

bash

undefined

Read a specific field

读取特定字段

op read "op://Development/AWS/access_key_id"

Read with JSON output

以JSON格式输出

op item get "AWS" --vault Development --format json

Read specific field from item

读取条目中的特定字段

op item get "AWS" --vault Development --fields access_key_id

undefined

op item get "AWS" --vault Development --fields access_key_id

undefined

Injecting Secrets into Commands

将密钥注入命令

The

op run

command injects secrets as environment variables:

bash

undefined

op run

命令可将密钥作为环境变量注入：

bash

undefined

Run command with secrets

运行包含密钥的命令

op run --env-file=.env.tpl -- ./deploy.sh

Example .env.tpl file:

示例.env.tpl文件：

AWS_ACCESS_KEY_ID=op://Development/AWS/access_key_id

AWS_SECRET_ACCESS_KEY=op://Development/AWS/secret_access_key

undefined

undefined

Injecting Secrets into Files

将密钥注入文件

The

op inject

command replaces secret references in template files:

bash

undefined

op inject

命令可替换模板文件中的密钥引用：

bash

undefined

Inject secrets from template to output file

将密钥从模板注入到输出文件

op inject -i config.tpl.yaml -o config.yaml

Example config.tpl.yaml:

示例config.tpl.yaml：

database:

host: localhost

password: op://Production/Database/password

undefined

undefined

Item Management

条目管理

Creating Items

创建条目

bash

undefined

bash

undefined

Create a login item

创建登录条目

op item create --category login
--title "My Service"
--vault Development
username=admin
password=secretpassword

Create with generated password

创建带自动生成密码的条目

op item create --category login
--title "New Account"
--generate-password

Create from JSON template

从JSON模板创建

op item create --template item.json

undefined

op item create --template item.json

undefined

Item Template (JSON)

条目模板（JSON）

json

{
  "title": "my-service-credentials",
  "vault": {"id": "vault-uuid-or-name"},
  "category": "LOGIN",
  "fields": [
    {"label": "username", "value": "admin", "type": "STRING"},
    {"label": "password", "value": "secret", "type": "CONCEALED"},
    {"label": "api_key", "value": "key123", "type": "CONCEALED"}
  ]
}

json

{
  "title": "my-service-credentials",
  "vault": {"id": "vault-uuid-or-name"},
  "category": "LOGIN",
  "fields": [
    {"label": "username", "value": "admin", "type": "STRING"},
    {"label": "password", "value": "secret", "type": "CONCEALED"},
    {"label": "api_key", "value": "key123", "type": "CONCEALED"}
  ]
}

Editing Items

编辑条目

bash

undefined

bash

undefined

Edit a field

编辑字段

op item edit "My Service" password=newpassword

Add a new field

添加新字段

op item edit "My Service" api_key=newkey

Edit with specific vault

编辑特定保管库中的条目

op item edit "My Service" --vault Development password=newpassword

undefined

op item edit "My Service" --vault Development password=newpassword

undefined

Service Accounts

服务账号

Service accounts enable automation without personal credentials.

服务账号无需个人凭据即可实现自动化操作。

Prerequisites

前提条件

1Password CLI version 2.18.0 or later
Active 1Password subscription
Admin permissions to create service accounts

1Password CLI版本2.18.0或更高
有效的1Password订阅
具备创建服务账号的管理员权限

Creating Service Accounts

创建服务账号

Via CLI:

bash

undefined

通过CLI创建：

bash

undefined

Create with read-only access

创建仅具有只读权限的账号

op service-account create "CI/CD Pipeline"
--vault Production:read_items

Create with write access

创建具有写入权限的账号

op service-account create "Deployment Bot"
--vault Production:read_items,write_items

Create with vault creation permission

创建具有保管库创建权限的账号

op service-account create "Provisioning Bot"
--vault Production:read_items,write_items
--can-create-vaults

undefined

op service-account create "Provisioning Bot"
--vault Production:read_items,write_items
--can-create-vaults

undefined

Using Service Accounts

使用服务账号

Export the service account token:

bash

export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

Then use normal CLI commands - they automatically authenticate with the service account.

导出服务账号令牌：

bash

export OP_SERVICE_ACCOUNT_TOKEN="ops_..."

随后即可使用常规CLI命令，系统会自动通过服务账号进行身份验证。

Service Account Limitations

服务账号限制

Cannot access Personal, Private, Employee, or default Shared vaults
Permissions cannot be modified after creation
Limited to 100 service accounts per account
Subject to rate limits

无法访问Personal、Private、Employee或默认Shared保管库
权限创建后无法修改
每个账号最多可创建100个服务账号
受速率限制约束

CI/CD Integration

CI/CD集成

GitHub Actions

yaml

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1

      - name: Load secrets
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          AWS_ACCESS_KEY_ID: op://CI-CD/AWS/access_key_id
          AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

      - name: Deploy
        run: ./deploy.sh

yaml

name: Deploy
on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install 1Password CLI
        uses: 1password/install-cli-action@v1

      - name: Load secrets
        uses: 1password/load-secrets-action@v2
        with:
          export-env: true
        env:
          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
          AWS_ACCESS_KEY_ID: op://CI-CD/AWS/access_key_id
          AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

      - name: Deploy
        run: ./deploy.sh

GitLab CI

yaml

deploy:
  image: 1password/op:2
  variables:
    OP_SERVICE_ACCOUNT_TOKEN: $OP_SERVICE_ACCOUNT_TOKEN
  script:
    - export AWS_ACCESS_KEY_ID=$(op read "op://CI-CD/AWS/access_key_id")
    - export AWS_SECRET_ACCESS_KEY=$(op read "op://CI-CD/AWS/secret_access_key")
    - ./deploy.sh

yaml

deploy:
  image: 1password/op:2
  variables:
    OP_SERVICE_ACCOUNT_TOKEN: $OP_SERVICE_ACCOUNT_TOKEN
  script:
    - export AWS_ACCESS_KEY_ID=$(op read "op://CI-CD/AWS/access_key_id")
    - export AWS_SECRET_ACCESS_KEY=$(op read "op://CI-CD/AWS/secret_access_key")
    - ./deploy.sh

CircleCI

yaml

version: 2.1
orbs:
  onepassword: onepassword/secrets@1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - onepassword/exec:
          command: ./deploy.sh
          env:
            AWS_ACCESS_KEY_ID: op://CI-CD/AWS/access_key_id
            AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

yaml

version: 2.1
orbs:
  onepassword: onepassword/secrets@1

jobs:
  deploy:
    docker:
      - image: cimg/base:stable
    steps:
      - checkout
      - onepassword/exec:
          command: ./deploy.sh
          env:
            AWS_ACCESS_KEY_ID: op://CI-CD/AWS/access_key_id
            AWS_SECRET_ACCESS_KEY: op://CI-CD/AWS/secret_access_key

External Secrets Operator Integration

External Secrets Operator集成

External Secrets Operator (ESO) syncs secrets from 1Password to Kubernetes.

External Secrets Operator（ESO）可将1Password中的密钥同步到Kubernetes。

Prerequisites

前提条件

1Password Connect Server (v1.5.6+)
Credentials file (
```
1password-credentials.json
```
)
Access token for authentication
External Secrets Operator installed in cluster

1Password Connect Server（v1.5.6+）
凭据文件（
```
1password-credentials.json
```
）
用于身份验证的访问令牌
已在集群中安装External Secrets Operator

Connect Server Setup

Connect Server设置

bash

undefined

bash

undefined

Create automation environment and get credentials

创建自动化环境并获取凭据

This generates 1password-credentials.json and an access token

此操作会生成1password-credentials.json和访问令牌

Create Kubernetes secret for Connect Server credentials

为Connect Server凭据创建Kubernetes Secret

kubectl create secret generic onepassword-credentials
--from-file=1password-credentials.json

Create secret for access token

为访问令牌创建Secret

kubectl create secret generic onepassword-token
--from-literal=token=your-access-token

undefined

kubectl create secret generic onepassword-token
--from-literal=token=your-access-token

undefined

Deploy Connect Server

部署Connect Server

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: onepassword-connect
spec:
  replicas: 1
  selector:
    matchLabels:
      app: onepassword-connect
  template:
    metadata:
      labels:
        app: onepassword-connect
    spec:
      containers:
        - name: connect-api
          image: 1password/connect-api:latest
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: credentials
              mountPath: /home/opuser/.op/1password-credentials.json
              subPath: 1password-credentials.json
      volumes:
        - name: credentials
          secret:
            secretName: onepassword-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: onepassword-connect
spec:
  selector:
    app: onepassword-connect
  ports:
    - port: 8080
      targetPort: 8080

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: onepassword-connect
spec:
  replicas: 1
  selector:
    matchLabels:
      app: onepassword-connect
  template:
    metadata:
      labels:
        app: onepassword-connect
    spec:
      containers:
        - name: connect-api
          image: 1password/connect-api:latest
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: credentials
              mountPath: /home/opuser/.op/1password-credentials.json
              subPath: 1password-credentials.json
      volumes:
        - name: credentials
          secret:
            secretName: onepassword-credentials
---
apiVersion: v1
kind: Service
metadata:
  name: onepassword-connect
spec:
  selector:
    app: onepassword-connect
  ports:
    - port: 8080
      targetPort: 8080

ClusterSecretStore Configuration

ClusterSecretStore配置

yaml

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: onepassword
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect:8080
      vaults:
        production: 1
        staging: 2
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token
            namespace: external-secrets
            key: token

yaml

apiVersion: external-secrets.io/v1
kind: ClusterSecretStore
metadata:
  name: onepassword
spec:
  provider:
    onepassword:
      connectHost: http://onepassword-connect:8080
      vaults:
        production: 1
        staging: 2
      auth:
        secretRef:
          connectTokenSecretRef:
            name: onepassword-token
            namespace: external-secrets
            key: token

ExternalSecret Examples

ExternalSecret示例

Basic secret retrieval:

yaml

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: database-credentials
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: Database             # Item title in 1Password
        property: username        # Field label
    - secretKey: password
      remoteRef:
        key: Database
        property: password

Using dataFrom with regex:

yaml

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: env-config
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: app-env
  dataFrom:
    - find:
        path: app-config          # Item title
        name:
          regexp: "^[A-Z_]+$"     # Match all uppercase env vars

基础密钥检索：

yaml

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: database-credentials
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: database-credentials
    creationPolicy: Owner
  data:
    - secretKey: username
      remoteRef:
        key: Database             # 1Password中的条目标题
        property: username        # 字段标签
    - secretKey: password
      remoteRef:
        key: Database
        property: password

使用dataFrom和正则表达式：

yaml

apiVersion: external-secrets.io/v1
kind: ExternalSecret
metadata:
  name: env-config
spec:
  refreshInterval: 1h
  secretStoreRef:
    kind: ClusterSecretStore
    name: onepassword
  target:
    name: app-env
  dataFrom:
    - find:
        path: app-config          # 条目标题
        name:
          regexp: "^[A-Z_]+$"     # 匹配所有大写环境变量

PushSecret (Kubernetes to 1Password)

PushSecret（Kubernetes到1Password）

yaml

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-generated-secret
spec:
  refreshInterval: 1h
  secretStoreRefs:
    - name: onepassword
      kind: ClusterSecretStore
  selector:
    secret:
      name: generated-credentials
  data:
    - match:
        secretKey: api-key
        remoteRef:
          remoteKey: generated-api-key
          property: password
      metadata:
        apiVersion: kubernetes.external-secrets.io/v1alpha1
        kind: PushSecretMetadata
        spec:
          vault: production
          tags:
            - generated
            - kubernetes

yaml

apiVersion: external-secrets.io/v1alpha1
kind: PushSecret
metadata:
  name: push-generated-secret
spec:
  refreshInterval: 1h
  secretStoreRefs:
    - name: onepassword
      kind: ClusterSecretStore
  selector:
    secret:
      name: generated-credentials
  data:
    - match:
        secretKey: api-key
        remoteRef:
          remoteKey: generated-api-key
          property: password
      metadata:
        apiVersion: kubernetes.external-secrets.io/v1alpha1
        kind: PushSecretMetadata
        spec:
          vault: production
          tags:
            - generated
            - kubernetes

1Password Kubernetes Operator

The native 1Password Operator provides direct integration without External Secrets Operator.

原生1Password Operator无需External Secrets Operator即可实现直接集成。

Installation via Helm

通过Helm安装

bash

helm repo add 1password https://1password.github.io/connect-helm-charts
helm install connect 1password/connect \
  --set-file connect.credentials=1password-credentials.json \
  --set operator.create=true \
  --set operator.token.value=your-access-token

bash

helm repo add 1password https://1password.github.io/connect-helm-charts
helm install connect 1password/connect \
  --set-file connect.credentials=1password-credentials.json \
  --set operator.create=true \
  --set operator.token.value=your-access-token

OnePasswordItem CRD

yaml

apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: database-secret
spec:
  itemPath: "vaults/Production/items/Database"

This creates a Kubernetes Secret named

database-secret

with all fields from the 1Password item.

yaml

apiVersion: onepassword.com/v1
kind: OnePasswordItem
metadata:
  name: database-secret
spec:
  itemPath: "vaults/Production/items/Database"

此配置会创建一个名为

database-secret

的Kubernetes Secret，包含1Password条目中的所有字段。

Auto-Restart Configuration

自动重启配置

Enable automatic deployment restarts when secrets change:

yaml

undefined

启用密钥变更时自动重启部署：

yaml

undefined

Operator-level (environment variable)

操作员级（环境变量）

AUTO_RESTART=true

Namespace-level (annotation)

命名空间级（注解）

apiVersion: v1 kind: Namespace metadata: name: production annotations: operator.1password.io/auto-restart: "true"

Deployment-level (annotation)

部署级（注解）

apiVersion: apps/v1 kind: Deployment metadata: annotations: operator.1password.io/auto-restart: "true"

undefined

apiVersion: apps/v1 kind: Deployment metadata: annotations: operator.1password.io/auto-restart: "true"

undefined

Shell Plugins

Shell插件

Shell plugins enable automatic authentication for third-party CLIs.

Shell插件可实现第三方CLI的自动身份验证。

Available Plugins

可用插件

bash

undefined

bash

undefined

List available plugins

列出可用插件

op plugin list

Common plugins: aws, gh, stripe, vercel, fly, etc.

常见插件：aws、gh、stripe、vercel、fly等

undefined

undefined

Plugin Setup

插件设置

bash

undefined

bash

undefined

Initialize AWS plugin

初始化AWS插件

op plugin init aws

This configures shell aliases to use 1Password for AWS credentials

此操作会配置Shell别名，使用1Password管理AWS凭据

Add to your shell profile as instructed

按照提示添加到Shell配置文件中

undefined

undefined

Git Workflow with 1Password

结合1Password使用Git工作流

Use 1Password to manage GitHub authentication for git operations (push, pull, clone).

使用1Password管理GitHub身份验证，用于git操作（push、pull、clone）。

Quick Setup

快速设置

Run the setup script to configure everything:

bash

./scripts/setup-gh-plugin.sh

运行设置脚本完成所有配置：

bash

./scripts/setup-gh-plugin.sh

Manual Setup

手动设置

Step 1: Initialize the gh plugin

步骤1：初始化gh插件

bash

undefined

bash

undefined

Sign in to 1Password

登录1Password

op signin

Initialize gh plugin (interactive - select your GitHub token)

初始化gh插件（交互式操作 - 选择你的GitHub令牌）

op plugin init gh

undefined

op plugin init gh

undefined

Step 2: Configure git credential helper

步骤2：配置git凭据助手

bash

undefined

bash

undefined

Remove any broken credential helpers

移除所有损坏的凭据助手

git config --global --unset-all credential.https://github.com.helper 2>/dev/null

Set gh as the credential helper for GitHub

将gh设置为GitHub的凭据助手

git config --global credential.https://github.com.helper '!/opt/homebrew/bin/gh auth git-credential' git config --global credential.https://gist.github.com.helper '!/opt/homebrew/bin/gh auth git-credential'

undefined

undefined

Step 3: Add shell integration

步骤3：添加Shell集成

Add to your

~/.zshrc

~/.bashrc

bash

undefined

将以下内容添加到

~/.zshrc

或

~/.bashrc

：

bash

undefined

1Password CLI plugins

1Password CLI插件

source ~/.config/op/plugins.sh

undefined

source ~/.config/op/plugins.sh

undefined

How It Works

工作原理

┌─────────────────────────────────────────────────────────────────┐
│                        Git Push Workflow                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   git push                                                       │
│      │                                                           │
│      ▼                                                           │
│   Git credential helper                                          │
│      │                                                           │
│      ▼                                                           │
│   gh auth git-credential                                         │
│      │                                                           │
│      ▼                                                           │
│   1Password plugin (via op wrapper)                              │
│      │                                                           │
│      ▼                                                           │
│   1Password (biometric/password unlock)                          │
│      │                                                           │
│      ▼                                                           │
│   Token retrieved and passed to git                              │
│      │                                                           │
│      ▼                                                           │
│   Push completes successfully                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                        Git Push工作流                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   git push                                                       │
│      │                                                           │
│      ▼                                                           │
│   Git凭据助手                                          │
│      │                                                           │
│      ▼                                                           │
│   gh auth git-credential                                         │
│      │                                                           │
│      ▼                                                           │
│   1Password插件（通过op包装器）                              │
│      │                                                           │
│      ▼                                                           │
│   1Password（生物识别/密码解锁）                          │
│      │                                                           │
│      ▼                                                           │
│   令牌被检索并传递给git                              │
│      │                                                           │
│      ▼                                                           │
│   Push操作成功完成                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Multiple GitHub Accounts

多GitHub账号

If you work with multiple GitHub accounts, you can configure per-repo credentials:

bash

undefined

如果你使用多个GitHub账号，可以按仓库配置凭据：

bash

undefined

For a specific repo, use a different 1Password item

针对特定仓库，使用不同的1Password条目

cd /path/to/work-repo git config credential.https://github.com.helper '!/opt/homebrew/bin/gh auth git-credential'

Or use includeIf in ~/.gitconfig for path-based selection

或在~/.gitconfig中使用includeIf实现基于路径的选择

[includeIf "gitdir:~/work/"] path = ~/.gitconfig-work

undefined

[includeIf "gitdir:~/work/"] path = ~/.gitconfig-work

undefined

Fixing Common Issues

常见问题修复

"Item not found in vault" error

“Item not found in vault”错误

This means the 1Password plugin is pointing to a deleted token:

bash

undefined

此错误表示1Password插件指向的令牌已被删除：

bash

undefined

Remove the broken plugin configuration

删除损坏的插件配置

rm ~/.config/op/plugins/used_items/gh.json

Re-initialize

重新初始化

op plugin init gh

undefined

op plugin init gh

undefined

gh aliased to op plugin run

gh被别名到op plugin run

gh

is aliased to run through 1Password but failing:

bash

undefined

如果

gh

被别名通过1Password运行但失败：

bash

undefined

Check the alias

检查别名

which gh # Shows: gh: aliased to op plugin run -- gh

which gh # 显示：gh: aliased to op plugin run -- gh

Run gh directly to bypass the alias

直接运行gh以绕过别名

/opt/homebrew/bin/gh auth status

undefined

/opt/homebrew/bin/gh auth status

undefined

Git prompting for username/password

Git提示输入用户名/密码

Verify the credential helper is configured:

bash

git config --list | grep credential

Should show:

credential.https://github.com.helper=!/opt/homebrew/bin/gh auth git-credential

验证凭据助手是否配置正确：

bash

git config --list | grep credential

应显示：

credential.https://github.com.helper=!/opt/homebrew/bin/gh auth git-credential

Troubleshooting

故障排除

Common Issues

常见问题

Authentication fails:

bash

undefined

身份验证失败：

bash

undefined

Check current session

检查当前会话

op whoami

Sign in again

重新登录

op signin

For service accounts, verify token

对于服务账号，验证令牌

echo $OP_SERVICE_ACCOUNT_TOKEN | head -c 10


**Item not found:**

```bash

echo $OP_SERVICE_ACCOUNT_TOKEN | head -c 10


**条目未找到：**

```bash

List items in vault to verify name

列出保管库中的条目以验证名称

op item list --vault "Vault Name"

op item list --vault "保管库名称"

Use item ID instead of name for reliability

使用条目ID而非名称以提高可靠性

op item get --vault Development dh7fjsh3kd8fjs


**Permission denied in CI/CD:**

```bash

op item get --vault Development dh7fjsh3kd8fjs


**CI/CD中权限被拒绝：**

```bash

Verify service account has access to vault

验证服务账号是否有权访问保管库

op vault list # Should show accessible vaults

op vault list # 应显示可访问的保管库

Check rate limits

检查速率限制

op service-account ratelimit


**External Secrets not syncing:**

```bash

op service-account ratelimit


**External Secrets未同步：**

```bash

Check ExternalSecret status

检查ExternalSecret状态

kubectl describe externalsecret <name>

kubectl describe externalsecret <名称>

Check Connect Server logs

检查Connect Server日志

kubectl logs -l app=onepassword-connect

Verify SecretStore connection

验证SecretStore连接

kubectl describe secretstore <name>

undefined

kubectl describe secretstore <名称>

undefined

Best Practices

最佳实践

Use secret references (
```
op://
```
) instead of hardcoding vault/item names in scripts
Prefer service accounts over personal accounts for automation
Scope permissions minimally - grant only necessary vault access
Use item IDs in scripts for stability (names can change)
Rotate service account tokens when sign-in addresses change
Enable auto-restart in Kubernetes for seamless secret rotation
Use separate vaults per environment (dev, staging, prod)
Tag items for organization and filtering

使用密钥引用（
```
op://
```
）而非在脚本中硬编码保管库/条目名称
优先使用服务账号而非个人账号进行自动化操作
最小化权限范围——仅授予必要的保管库访问权限
在脚本中使用条目ID以提高稳定性（名称可能变更）
当登录地址变更时轮换服务账号令牌
在Kubernetes中启用自动重启以实现密钥变更时的无缝重启
按环境使用独立保管库（开发、测试、生产）
为条目添加标签以便于组织和过滤

Resources

资源

References

参考文档

```
references/cli-commands.md
```
- Complete CLI command reference
```
references/kubernetes-examples.md
```
- Kubernetes manifest examples
```
references/python-sdk.md
```
- Python SDK reference and integration guide
```
references/environments/README.md
```
- Developer Environments guide
```
references/environments/inventory.md
```
- Current environments inventory

```
references/cli-commands.md
```
- 完整CLI命令参考
```
references/kubernetes-examples.md
```
- Kubernetes清单示例
```
references/python-sdk.md
```
- Python SDK参考和集成指南
```
references/environments/README.md
```
- 开发者环境指南
```
references/environments/inventory.md
```
- 当前环境清单

Tools

工具

Environment management CLI tools in TypeScript and Python:

Operation	TypeScript ( `tools/` )	Python ( `tools-python/` )
Create	`bun run create`	`uv run op-env-create`
Update	`bun run update`	`uv run op-env-update`
Delete	`bun run delete`	`uv run op-env-delete`
Show	`bun run show`	`uv run op-env-show`
List	`bun run list`	`uv run op-env-list`
Export	`bun run export`	`uv run op-env-export`

TypeScript requirements: Bun runtime Python requirements: Python 3.9+, uv,

OP_SERVICE_ACCOUNT_TOKEN

bash

undefined

TypeScript和Python版本的环境管理CLI工具：

操作	TypeScript（ `tools/` ）	Python（ `tools-python/` ）
创建	`bun run create`	`uv run op-env-create`
更新	`bun run update`	`uv run op-env-update`
删除	`bun run delete`	`uv run op-env-delete`
查看	`bun run show`	`uv run op-env-show`
列出	`bun run list`	`uv run op-env-list`
导出	`bun run export`	`uv run op-env-export`

TypeScript要求： Bun运行时 Python要求： Python 3.9+、uv、

OP_SERVICE_ACCOUNT_TOKEN

bash

undefined

TypeScript tools

TypeScript工具

cd tools && bun run src/op-env-list.ts --help

Python SDK tools

Python SDK工具

cd tools-python && uv sync && uv run op-env-list --help

undefined

cd tools-python && uv sync && uv run op-env-list --help

undefined

Templates

模板

Environment and integration templates (in

templates/

Template	Description
`env.template`	Standard .env file template
`env-op-refs.template`	Template with op:// references
`github-actions-env.yaml`	GitHub Actions workflow example
`docker-compose-env.yaml`	Docker Compose with secrets injection

环境和集成模板（位于

templates/

）：

模板	描述
`env.template`	标准.env文件模板
`env-op-refs.template`	包含op://引用的模板
`github-actions-env.yaml`	GitHub Actions工作流示例
`docker-compose-env.yaml`	集成密钥注入的Docker Compose示例

Scripts

脚本

```
scripts/setup-gh-plugin.sh
```
- Setup GitHub CLI with 1Password integration
```
scripts/setup-service-account.sh
```
- Create and configure a service account
```
scripts/sync-check.sh
```
- Verify External Secrets synchronization

```
scripts/setup-gh-plugin.sh
```
- 配置GitHub CLI与1Password集成
```
scripts/setup-service-account.sh
```
- 创建并配置服务账号
```
scripts/sync-check.sh
```
- 验证External Secrets同步状态