Automatisch 集成 GitLabOAuth 应用注册与连接配置完整指南【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch本文基于 Automatisch 官方连接文档完整讲解如何在 GitLab 上注册 OAuth 应用程序并与 Automatisch 建立连接。读完本文你将掌握GitLab OAuth 应用的注册步骤与 Scope 选择、Automatisch 连接表单中各项凭证的对应关系、自托管 GitLab 实例的配置方法以及连接建立后认证凭据在源码层面的工作方式授权码换取、刷新、校验。一、GitLab 连接是什么Automatisch 是一款开源的工作流自动化平台。连接Connection是 Automatisch 与第三方服务之间建立的授权关系只有先建立连接才能在流程Flow中调用该应用的触发器与动作。GitLab 应用在 Automatisch 中通过OAuth 2.0 授权码流程Authorization Code Flow完成认证。应用定义位于 packages/backend/src/apps/gitlab/index.js其关键元信息如下应用名称GitLab标识键gitlab官方托管地址与 API 地址https://gitlab.com品牌色#FC6D26GitLab 橙支持连接supportsConnections: true认证文档入口{DOCS_URL}/apps/gitlab/connection也就是说你在 GitLab 侧创建的是“应用程序”OAuth Application在 Automatisch 侧创建的是“连接”。连接文档原文位于 packages/docs/pages/apps/gitlab/connection.md。二、前置条件在开始注册前请确认你拥有一个GitLab 账号默认面向https://gitlab.com官方托管服务自托管实例的适配见下文第六节。你能够登录Automatisch 实例并具备添加连接的权限。浏览器同时打开 GitLab 与 Automatisch 两个页面便于在两处之间复制粘贴凭证。三、在 GitLab 上注册新的 OAuth 应用按照连接文档的第一步到第六步在 GitLab 侧完成 OAuth 应用的创建第 1 步进入 GitLab 的应用程序注册页面访问 GitLab 用户设置中的“Applications”页面文档给出的入口为https://gitlab.com/-/profile/applications点击页面上的“New application”或“注册新应用程序”按钮即可看到新建表单。第 2 步填写应用名称Name为应用起一个可辨识的名称例如Automatisch。该名称将显示在你的 GitLab 授权页面上建议使用能够区分来源的命名方便日后审计和撤销。第 3 步配置重定向 URIRedirect URI在 Automatisch 的连接添加页面路径为/app/gitlab/connections/add页面上会展示一个只读字段OAuth Redirect URL其默认值形如{WEB_APP_URL}/app/gitlab/connections/add将这一整串地址完整复制粘贴到 GitLab 的Redirect URI字段中。该地址告诉 GitLab 授权成功后把授权码回调到哪里是 OAuth 流程能否走通的关键必须逐字符完全一致包括协议、域名、路径大小写。从源码看这一回调地址并非写死而是由 Automatisch 的 Web 应用地址WEB_APP_URL环境变量动态拼装定义于 packages/backend/src/apps/gitlab/auth/index.js{ key: oAuthRedirectUrl, label: OAuth Redirect URL, type: string, required: true, readOnly: true, value: {WEB_APP_URL}/app/gitlab/connections/add, clickToCopy: true, }由于该字段是只读且支持一键复制clickToCopy: true建议直接在 Automatisch 界面点击复制图标避免手输出错。第 4 步勾选“Confidential”机密选项GitLab 的 OAuth 应用分为“机密”与“非机密”两类。Automatisch 的后端使用 Client Secret 换取令牌因此必须将应用标记为ConfidentialGitLab 才会下发 Client Secret 供后续授权码交换使用。第 5 步勾选需要的 Scopes权限范围在 Scopes 区域至少勾选以下两项Scope用途api授予对 GitLab API 的完整读写权限是工作流执行如读取项目、创建 Issue、触发 CI 等所需的核心范围read_user允许读取当前登录用户的公开与私有基本信息用户名、ID 等用于认证时的用户身份校验与显示这两个 Scope 与源码中定义的一致——generate-auth-url.js 中写死了授权范围const scopes [api, read_user];因此如果你后续在 Automatisch 中勾选了超出这两个范围的 Scope 或不包含这两个范围授权或令牌校验都可能失败。第 6 步保存应用点击表单底部的Save application保存应用程序按钮提交。四、将凭证填入 Automatisch应用创建成功后GitLab 会跳转到应用详情页并展示两个关键值Application ID应用 ID和Secret密钥。连接文档第七至第十一步描述的就是凭证回填与最终建立连接的过程。第 78 步复制凭证将 GitLab 详情页的Application ID复制到 Automatisch 的Client ID字段将 GitLab 详情页的Secret复制到 Automatisch 的Client Secret字段。这两个字段对应 auth/index.js 中的clientId与clientSecret均为必填项required: true。第 910 步触发授权与完成提交点击 GitLab 页面上的Continue按钮再点击 Automatisch 页面的Submit按钮。此时 Automatisch 会使用你填写的 Client ID、预先配置的回调地址以及 Scope构造授权 URL 并打开 GitLab 授权页见 generate-auth-url.jsconst searchParams new URLSearchParams({ client_id: $.auth.data.clientId, redirect_uri: $.auth.data.oAuthRedirectUrl, scope: scopes.join( ), // api read_user response_type: code, state: Date.now().toString(), });你在 GitLab 页面确认授权后GitLab 将授权码回调到 AutomatischAutomatisch 用授权码换取访问令牌与刷新令牌并校验当前登录用户身份。第 11 步完成连接建立成功后即可在流程编辑器中选择该连接开始使用 GitLab 的触发器和动作可用的 13 种事件触发器见下文第七节。说明连接文档末尾原文写作“Start using your newGithubconnection”结合上下文可以判断这是文档笔误实际建立的是 GitLab 连接。五、凭证校验与存储的底层原理连接并非只保存 Client ID 与 Client SecretAutomatisch 在授权完成后会持久化一整套认证数据。以 verify-credentials.js 为例其内部依次完成向/oauth/token发起POST请求携带client_id、client_secret、授权码code、grant_type: authorization_code与redirect_uri换取access_token与refresh_token调用 GitLab APIGET /v4/user见 get-current-user.js获取当前用户信息组装并保存screenName格式为“用户名 实例地址”例如zhangsan https://gitlab.com连同accessToken、refreshToken、scope、tokenType、userId一起写入连接数据。在后续使用中令牌注入每次请求 GitLab API 前add-auth-header.js 会为请求头附加Authorization: Bearer accessToken令牌刷新当访问令牌过期时refresh-token.js 使用grant_type: refresh_token与存储的 refresh token 换取新的访问令牌避免流程中断连接有效性检查is-still-verified.js 通过再次调用当前用户接口并判断返回的user.id是否存在来确认连接仍然有效。六、支持自托管 GitLab 实例除官方https://gitlab.com外Automatisch 的 GitLab 应用还允许连接自托管self-hosted的 GitLab 实例。在 Automatisch 连接表单中有一个可选字段Gitlab instance URL默认值为https://gitlab.com你可以在自建实例时将其改为例如https://gitlab.example.com。该字段的底层影响体现在两处授权地址与令牌接口均基于实例地址拼接见 generate-auth-url.js 与 refresh-token.js 中对/oauth/authorize、/oauth/token的调用业务请求的基础地址由 set-base-url.js 与 get-base-url.js 统一解析优先取instanceUrl其次取应用定义的apiBaseUrl最后回退到baseUrl。需要注意自托管实例的版本必须支持文档所述的 OAuth 2.0 授权码流程与 GitLab API/v4路径连接才会正常工作。七、连接完成后可用的触发器概览连接建立后即可在流程中配置 GitLab 触发器。Automatisch 的 GitLab 应用内置了 13 种基于 Webhook 的事件触发器注册与退订逻辑见 triggers/lib.js完整清单见 triggers/index.js 与 triggers.md触发器触发时机Push event向仓库推送代码Issue eventIssue 被创建、更新、关闭或重新打开Confidential issue event机密 Issue 被创建或更新、关闭、重新打开Merge request event合并请求被创建、更新或关闭Comment event在提交、合并请求、Issue、代码片段上产生新评论Confidential comment event在上述对象上产生新的机密评论Pipeline event流水线状态发生变化Job eventCI Job 状态发生变化Deployment event部署开始、成功、失败或被取消Feature flag event特性开关被打开或关闭Release eventRelease 被创建或更新Tag event在仓库中创建或删除标签Wiki page eventWiki 页面被创建、更新或删除这些触发器在注册时会调用 GitLab 项目 Hook 接口POST /v4/projects/{projectId}/hooks并将 Automatisch 的 Webhook 地址、webhookSecretKey作为令牌写入订阅配置流程停用时会通过DELETE /v4/projects/{projectId}/hooks/{id}自动退订。八、常见问题与注意事项授权失败或回调 404绝大多数情况是 Redirect URI 与 Automatisch 显示的 OAuth Redirect URL 不一致请逐字符核对含结尾斜杠。同时确认 GitLab 应用已勾选Confidential。连接校验失败检查 Scope 是否同时包含api与read_user。缺少read_user会导致GET /v4/user无法返回有效身份进而被 is-still-verified.js 判定为失效。访问令牌过期Automatisch 会利用存储的 refresh token 自动刷新一般无需人工干预若长时间未使用导致 refresh token 失效需重新创建连接。自托管实例连不上确认实例可被 Automatisch 后端网络访问、版本支持/v4API并在 Instance URL 字段填写正确地址。凭证泄露风险Client Secret 与令牌属于敏感信息请在受信任的环境中创建连接若怀疑泄露可在 GitLab 的 Applications 页面撤销或重建应用再在 Automatisch 中重新添加连接。至此GitLab 连接已经就绪你可以在 Automatisch 中基于 Issue、合并请求、流水线等事件搭建自动化流程了。若连接文档中描述的步骤与 GitLab 官方界面存在出入以你当前 GitLab 版本的实际界面为准并向项目反馈更新。【免费下载链接】automatischThe open source Zapier alternative. Build workflow automation without spending time and money.项目地址: https://gitcode.com/GitHub_Trending/au/automatisch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考