From d7e8f843ad531b6d79c80b746a414190d940e85d Mon Sep 17 00:00:00 2001 From: Rohit Malhotra Date: Tue, 15 Apr 2025 17:25:25 -0400 Subject: [PATCH] [Docs]: Add GitLab token setup documentation (#7635) Co-authored-by: openhands --- .../current/usage/how-to/gui-mode.md | 53 ++++++++++++++++--- .../current/usage/how-to/gui-mode.md | 48 ++++++++++++++++- .../current/usage/how-to/gui-mode.md | 48 ++++++++++++++++- .../current/usage/how-to/gui-mode.md | 53 ++++++++++++++++--- docs/modules/usage/how-to/gui-mode.md | 48 ++++++++++++++++- 5 files changed, 232 insertions(+), 18 deletions(-) diff --git a/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md b/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md index a250c17956..4ae04026ca 100644 --- a/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md +++ b/docs/i18n/fr/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md @@ -21,14 +21,18 @@ OpenHands fournit un mode Interface Graphique (GUI) convivial pour interagir ave 3. Entrez la `Clé API` correspondante pour le fournisseur choisi. 4. Cliquez sur "Enregistrer" pour appliquer les paramètres. -### Configuration du Jeton GitHub +### Jetons de Contrôle de Version + +OpenHands prend en charge plusieurs fournisseurs de contrôle de version. Vous pouvez configurer des jetons pour plusieurs fournisseurs simultanément. + +#### Configuration du Jeton GitHub OpenHands exporte automatiquement un `GITHUB_TOKEN` vers l'environnement shell s'il est disponible. Cela peut se produire de deux manières : 1. **Localement (OSS)** : L'utilisateur saisit directement son jeton GitHub 2. **En ligne (SaaS)** : Le jeton est obtenu via l'authentification OAuth GitHub -#### Configuration d'un Jeton GitHub Local +##### Configuration d'un Jeton GitHub Local 1. **Générer un Personal Access Token (PAT)** : - Allez dans Paramètres GitHub > Paramètres développeur > Personal Access Tokens > Tokens (classique) @@ -40,11 +44,11 @@ OpenHands exporte automatiquement un `GITHUB_TOKEN` vers l'environnement shell s 2. **Entrer le Jeton dans OpenHands** : - Cliquez sur le bouton Paramètres (icône d'engrenage) en haut à droite - - Accédez à la section "GitHub" + - Accédez à la section "Git Provider Settings" - Collez votre jeton dans le champ "Jeton GitHub" - Cliquez sur "Enregistrer" pour appliquer les modifications -#### Politiques de Jetons Organisationnels +##### Politiques de Jetons Organisationnels Si vous travaillez avec des dépôts organisationnels, une configuration supplémentaire peut être nécessaire : @@ -59,7 +63,7 @@ Si vous travaillez avec des dépôts organisationnels, une configuration supplé - Si nécessaire, cliquez sur "Activer SSO" à côté de votre organisation - Terminez le processus d'autorisation SSO -#### Authentification OAuth (Mode En Ligne) +##### Authentification OAuth (Mode En Ligne) Lorsque vous utilisez OpenHands en mode en ligne, le flux OAuth GitHub : @@ -74,7 +78,7 @@ Lorsque vous utilisez OpenHands en mode en ligne, le flux OAuth GitHub : - Autorisez OpenHands à accéder à votre compte GitHub - Si vous utilisez une organisation, autorisez l'accès à l'organisation si vous y êtes invité -#### Dépannage +##### Dépannage Problèmes courants et solutions : @@ -95,6 +99,43 @@ Problèmes courants et solutions : - Vérifiez la console du navigateur pour tout message d'erreur - Utilisez le bouton "Tester la connexion" dans les paramètres s'il est disponible +#### Configuration du Jeton GitLab + +OpenHands exporte automatiquement un `GITLAB_TOKEN` vers l'environnement shell, uniquement pour les installations locales, s'il est disponible. + +##### Configuration d'un Jeton GitLab + +1. **Générer un Personal Access Token (PAT)** : + - Sur GitLab, allez dans Paramètres utilisateur > Jetons d'accès + - Créez un nouveau jeton avec les portées suivantes : + - `api` (Accès API) + - `read_user` (Lecture des informations utilisateur) + - `read_repository` (Lecture du dépôt) + - `write_repository` (Écriture du dépôt) + - Définissez une date d'expiration ou laissez vide pour un jeton sans expiration + +2. **Entrer le Jeton dans OpenHands** : + - Cliquez sur le bouton Paramètres (icône d'engrenage) + - Accédez à la section `Git Provider Settings` + - Collez votre jeton dans le champ `Jeton GitLab` + - Si vous utilisez GitLab auto-hébergé, entrez l'URL de votre instance GitLab + - Cliquez sur `Enregistrer les modifications` pour appliquer les changements + +##### Dépannage + +Problèmes courants et solutions : + +1. **Jeton Non Reconnu** : + - Assurez-vous que le jeton est correctement enregistré dans les paramètres + - Vérifiez que le jeton n'a pas expiré + - Vérifiez que le jeton a les portées requises + - Pour les instances auto-hébergées, vérifiez l'URL correcte de l'instance + +2. **Accès Refusé** : + - Vérifiez les permissions d'accès au projet + - Vérifiez si le jeton possède les portées nécessaires + - Pour les dépôts de groupe/organisation, assurez-vous d'avoir les accès appropriés + ### Paramètres Avancés 1. Basculez sur `Options Avancées` pour accéder aux paramètres supplémentaires. diff --git a/docs/i18n/ja/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md b/docs/i18n/ja/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md index a938f8e132..83b113e8a8 100644 --- a/docs/i18n/ja/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md +++ b/docs/i18n/ja/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md @@ -16,7 +16,11 @@ OpenHandsは、AI アシスタントとやり取りするためのグラフィ 3. 選択したプロバイダーに対応する`API Key`を入力します。 4. `Save Changes`をクリックして設定を適用します。 -### GitHubトークンの設定 +### バージョン管理トークン + +OpenHandsは複数のバージョン管理プロバイダーをサポートしています。複数のプロバイダーのトークンを同時に設定できます。 + +#### GitHubトークンの設定 OpenHandsは、利用可能な場合、自動的に`GITHUB_TOKEN`をシェル環境にエクスポートします。これは2つの方法で行われます。 @@ -34,7 +38,7 @@ OpenHandsは、利用可能な場合、自動的に`GITHUB_TOKEN`をシェル環 - Minimal Permissions（検索用に**Meta Data = Read-only**を選択し、ブランチ作成用に**Pull Requests = Read and Write**、**Content = Read and Write**を選択します） 2. **OpenHandsにトークンを入力**: - 設定ボタン（歯車アイコン）をクリックします。 - - `GitHub Settings`セクションに移動します。 + - `Git Provider Settings`セクションに移動します。 - `GitHub Token`フィールドにトークンを貼り付けます。 - `Save Changes`をクリックして変更を適用します。 @@ -94,6 +98,46 @@ OpenHandsは、利用可能な場合、自動的に`GITHUB_TOKEN`をシェル環 - 組織を使用している場合は、プロンプトが表示されたら組織へのアクセスを承認します。 +#### GitLabトークンの設定 + +OpenHandsは、利用可能な場合、ローカルインストールのみ、自動的に`GITLAB_TOKEN`をシェル環境にエクスポートします。 + +
+ GitLabトークンの設定 + + 1. **Personal Access Token（PAT）の生成**: + - GitLabで、User Settings > Access Tokensに移動します。 + - 以下のスコープを持つ新しいトークンを作成します: + - `api`（APIアクセス） + - `read_user`（ユーザー情報の読み取り） + - `read_repository`（リポジトリ読み取り） + - `write_repository`（リポジトリ書き込み） + - 有効期限を設定するか、無期限トークンの場合は空白のままにします。 + 2. **OpenHandsにトークンを入力**: + - 設定ボタン（歯車アイコン）をクリックします。 + - `Git Provider Settings`セクションに移動します。 + - `GitLab Token`フィールドにトークンを貼り付けます。 + - セルフホスト型GitLabを使用している場合は、GitLabインスタンスのURLを入力します。 + - `Save Changes`をクリックして変更を適用します。 +
+ +
+ トラブルシューティング + + 一般的な問題と解決策: + + - **トークンが認識されない**: + - トークンが設定に正しく保存されていることを確認します。 + - トークンの有効期限が切れていないことを確認します。 + - トークンに必要なスコープがあることを確認します。 + - セルフホスト型インスタンスの場合は、正しいインスタンスURLを確認します。 + + - **アクセスが拒否された**: + - プロジェクトのアクセス権限を確認します。 + - トークンに必要なスコープがあるかどうかを確認します。 + - グループ/組織のリポジトリの場合は、適切なアクセス権があることを確認します。 +
+ ### 高度な設定 1. 設定ページ内で、`Advanced`オプションを切り替えて追加の設定にアクセスします。 diff --git a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md index 8fb70f48bf..45e64d0463 100644 --- a/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md +++ b/docs/i18n/pt-BR/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md @@ -17,7 +17,11 @@ O OpenHands fornece um modo de Interface Gráfica do Usuário (GUI) para interag 3. Insira a `Chave de API` correspondente para o provedor escolhido. 4. Clique em `Salvar Alterações` para aplicar as configurações. -### Configuração do Token do GitHub +### Tokens de Controle de Versão + +O OpenHands suporta múltiplos provedores de controle de versão. Você pode configurar tokens para vários provedores simultaneamente. + +#### Configuração do Token do GitHub O OpenHands exporta automaticamente um `GITHUB_TOKEN` para o ambiente shell se ele estiver disponível. Isso pode acontecer de duas maneiras: @@ -35,7 +39,7 @@ O OpenHands exporta automaticamente um `GITHUB_TOKEN` para o ambiente shell se e - Minimal Permissions (Selecione **Meta Data = Read-only** para pesquisa, **Pull Requests = Read and Write**, **Content = Read and Write** para criação de branches) 2. **Insira o Token no OpenHands**: - Clique no botão Settings (ícone de engrenagem). - - Navegue até a seção `GitHub Settings`. + - Navegue até a seção `Git Provider Settings`. - Cole seu token no campo `GitHub Token`. - Clique em `Save Changes` para aplicar as alterações. @@ -95,6 +99,46 @@ O OpenHands exporta automaticamente um `GITHUB_TOKEN` para o ambiente shell se e - Se estiver usando uma organização, autorize o acesso à organização se solicitado. +#### Configuração do Token do GitLab + +O OpenHands exporta automaticamente um `GITLAB_TOKEN` para o ambiente shell, apenas para instalações locais, se ele estiver disponível. + +
+ Configurando um Token do GitLab + + 1. **Gere um Personal Access Token (PAT)**: + - No GitLab, vá para User Settings > Access Tokens. + - Crie um novo token com os seguintes escopos: + - `api` (Acesso à API) + - `read_user` (Leitura de informações do usuário) + - `read_repository` (Leitura do repositório) + - `write_repository` (Escrita no repositório) + - Defina uma data de expiração ou deixe em branco para um token sem expiração. + 2. **Insira o Token no OpenHands**: + - Clique no botão Settings (ícone de engrenagem). + - Navegue até a seção `Git Provider Settings`. + - Cole seu token no campo `GitLab Token`. + - Se estiver usando GitLab auto-hospedado, insira a URL da sua instância GitLab. + - Clique em `Save Changes` para aplicar as alterações. +
+ +
+ Solução de Problemas + + Problemas comuns e soluções: + + - **Token Não Reconhecido**: + - Certifique-se de que o token esteja salvo corretamente nas configurações. + - Verifique se o token não expirou. + - Verifique se o token possui os escopos necessários. + - Para instâncias auto-hospedadas, verifique a URL correta da instância. + + - **Acesso Negado**: + - Verifique as permissões de acesso ao projeto. + - Verifique se o token possui os escopos necessários. + - Para repositórios de grupo/organização, certifique-se de ter o acesso adequado. +
+ ### Configurações Avançadas 1. Dentro da página Settings, ative as opções `Advanced` para acessar configurações adicionais. diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md index 3cd9def4ac..396fa49454 100644 --- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/current/usage/how-to/gui-mode.md @@ -19,14 +19,18 @@ OpenHands 提供了一个用户友好的图形用户界面（GUI）模式，用 3. 输入所选提供商对应的 `API Key`。 4. 点击"保存"应用设置。 -### GitHub Token 设置 +### 版本控制令牌 + +OpenHands 支持多个版本控制提供商。您可以同时配置多个提供商的令牌。 + +#### GitHub Token 设置 如果可用，OpenHands 会自动将 `GITHUB_TOKEN` 导出到 shell 环境中。这可以通过两种方式实现： 1. **本地（OSS）**：用户直接输入他们的 GitHub token 2. **在线（SaaS）**：通过 GitHub OAuth 身份验证获取 token -#### 设置本地 GitHub Token +##### 设置本地 GitHub Token 1. **生成个人访问令牌（PAT）**： - 转到 GitHub 设置 > 开发者设置 > 个人访问令牌 > 令牌（经典） @@ -38,11 +42,11 @@ OpenHands 提供了一个用户友好的图形用户界面（GUI）模式，用 2. **在 OpenHands 中输入令牌**： - 点击右上角的设置按钮（齿轮图标） - - 导航到"GitHub"部分 + - 导航到"Git Provider Settings"部分 - 将令牌粘贴到"GitHub Token"字段中 - 点击"保存"应用更改 -#### 组织令牌策略 +##### 组织令牌策略 如果您使用组织仓库，可能需要额外的设置： @@ -57,7 +61,7 @@ OpenHands 提供了一个用户友好的图形用户界面（GUI）模式，用 - 如果需要，点击组织旁边的"启用 SSO" - 完成 SSO 授权过程 -#### OAuth 身份验证（在线模式） +##### OAuth 身份验证（在线模式） 在在线模式下使用 OpenHands 时，GitHub OAuth 流程： @@ -72,7 +76,7 @@ OpenHands 提供了一个用户友好的图形用户界面（GUI）模式，用 - 授权 OpenHands 访问您的 GitHub 帐户 - 如果使用组织，在出现提示时授权组织访问 -#### 故障排除 +##### 故障排除 常见问题和解决方案： @@ -93,6 +97,43 @@ OpenHands 提供了一个用户友好的图形用户界面（GUI）模式，用 - 检查浏览器控制台中是否有任何错误消息 - 如果可用，使用设置中的"测试连接"按钮 +#### GitLab Token 设置 + +OpenHands 会自动将 `GITLAB_TOKEN` 导出到 shell 环境中，仅适用于本地安装，如果它可用的话。 + +##### 设置 GitLab Token + +1. **生成个人访问令牌（PAT）**： + - 在 GitLab 中，转到用户设置 > 访问令牌 + - 创建具有以下范围的新令牌： + - `api`（API 访问） + - `read_user`（读取用户信息） + - `read_repository`（读取仓库） + - `write_repository`（写入仓库） + - 设置过期日期或留空以获取永不过期的令牌 + +2. **在 OpenHands 中输入令牌**： + - 点击设置按钮（齿轮图标） + - 导航到 `Git Provider Settings` 部分 + - 将令牌粘贴到 `GitLab Token` 字段中 + - 如果使用自托管 GitLab，请输入您的 GitLab 实例 URL + - 点击 `Save Changes` 应用更改 + +##### 故障排除 + +常见问题和解决方案： + +1. **令牌无法识别**： + - 确保令牌已正确保存在设置中 + - 检查令牌是否已过期 + - 验证令牌是否具有所需的范围 + - 对于自托管实例，验证正确的实例 URL + +2. **访问被拒绝**： + - 验证项目访问权限 + - 检查令牌是否具有必要的范围 + - 对于组/组织仓库，确保您拥有适当的访问权限 + ### 高级设置 1. 切换`高级选项`以访问其他设置。 diff --git a/docs/modules/usage/how-to/gui-mode.md b/docs/modules/usage/how-to/gui-mode.md index cd0e3364e7..5fef35dc58 100644 --- a/docs/modules/usage/how-to/gui-mode.md +++ b/docs/modules/usage/how-to/gui-mode.md @@ -18,7 +18,11 @@ OpenHands provides a Graphical User Interface (GUI) mode for interacting with th 3. Enter the corresponding `API Key` for your chosen provider. 4. Click `Save Changes` to apply the settings. -### GitHub Token Setup +### Version Control Tokens + +OpenHands supports multiple version control providers. You can configure tokens for multiple providers simultaneously. + +#### GitHub Token Setup OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if it is available. This can happen in two ways: @@ -36,7 +40,7 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if it - Minimal Permissions ( Select `Meta Data = Read-only` read for search, `Pull Requests = Read and Write` and `Content = Read and Write` for branch creation) 2. **Enter Token in OpenHands**: - Click the Settings button (gear icon). - - Navigate to the `GitHub Settings` section. + - Navigate to the `Git Provider Settings` section. - Paste your token in the `GitHub Token` field. - Click `Save Changes` to apply the changes. @@ -96,6 +100,46 @@ OpenHands automatically exports a `GITHUB_TOKEN` to the shell environment if it - If using an organization, authorize organization access if prompted. +#### GitLab Token Setup + +OpenHands automatically exports a `GITLAB_TOKEN` to the shell environment, for local installations only, if it is available. + +
+ Setting Up a GitLab Token + + 1. **Generate a Personal Access Token (PAT)**: + - On GitLab, go to User Settings > Access Tokens. + - Create a new token with the following scopes: + - `api` (API access) + - `read_user` (Read user information) + - `read_repository` (Read repository) + - `write_repository` (Write repository) + - Set an expiration date or leave it blank for a non-expiring token. + 2. **Enter Token in OpenHands**: + - Click the Settings button (gear icon). + - Navigate to the `Git Provider Settings` section. + - Paste your token in the `GitLab Token` field. + - Enter your GitLab instance URL if using self-hosted GitLab. + - Click `Save Changes` to apply the changes. +
+ +
+ Troubleshooting + + Common issues and solutions: + + - **Token Not Recognized**: + - Ensure the token is properly saved in settings. + - Check that the token hasn't expired. + - Verify the token has the required scopes. + - For self-hosted instances, verify the correct instance URL. + + - **Access Denied**: + - Verify project access permissions. + - Check if the token has the necessary scopes. + - For group/organization repositories, ensure you have proper access. +
+ ### Advanced Settings 1. Inside the Settings page, toggle `Advanced` options to access additional settings.