#### Overview Implement an automated CI/CD pipeline to regularly fetch and import the OpenAPI 3.0 specification to keep [API documentation](https://gitlab.com/gitlab-com/gl-infra/api-docs) synchronized with source specification. #### Architecture - Scheduled CI job runs on a defined interval (e.g. hourly/daily/weekly) - Executes `fetch-spec` [script](https://gitlab.com/gitlab-com/gl-infra/api-docs/-/blob/main/scripts/fetch-spec.js?ref_type=heads) to retrieve the latest OpenAPI [spec](https://gitlab.com/gitlab-org/gitlab/-/raw/master/doc/api/openapi/openapi_v3.yaml) - Commits changes to a dedicated branch - Opens an automated merge request for review - Uses a bot token stored securely in Vault #### Implementation Steps **1. Infrastructure Setup** Add a project access token for spec-import-bot in [`project_api_docs.tf`](https://gitlab.com/gitlab-com/gl-infra/infra-mgmt/-/blob/main/environments/gitlab-com/project_api_docs.tf): - Create bot token with developer access and API scope - Store token in Vault for secure access - Configure token rotation module **2. CI/CD Pipeline Job** Add a scheduled job to [`.gitlab-ci.yml`](https://gitlab.com/gitlab-com/gl-infra/api-docs/-/blob/main/.gitlab-ci.yml?ref_type=heads): - Runs on schedule - Configures bot credentials - Fetches spec using existing fetch-spec script - Commits changes to `ci/import-spec` branch - Creates merge request automatically, handling no-changes scenario **3. Script Enhancement** Enhance [`scripts/fetch-spec.js`](https://gitlab.com/gitlab-com/gl-infra/api-docs/-/blob/main/scripts/fetch-spec.js?ref_type=heads): - Add validation for YAML parsing and OpenAPI structure - Improve error handling for network failures - Log fetch timestamp and source URL #### Benefits - Consistency with source of truth - No manual fetch/commit steps - Full auditability via git history - Safety through MR review process - Reusable pattern for other automated imports #### Trade-offs and Future Improvements **Current Approach (Human-in-the-Loop):** - Requires manual approval before merging - Provides safety net to review changes - Allows team to validate spec quality **Future Enhancement (Auto-Approval):** - Could implement automatic approval once confidence is established - Would require safeguards like automated validation and diff analysis - Would eliminate manual review overhead for routine updates