{"id":18867679,"url":"https://github.com/devowlio/node-gitlab-ci","last_synced_at":"2025-10-08T09:17:13.354Z","repository":{"id":47976017,"uuid":"265246948","full_name":"devowlio/node-gitlab-ci","owner":"devowlio","description":"Dynamically create your .gitlab-ci.yml from TypeScript .ts files!","archived":false,"fork":false,"pushed_at":"2023-03-21T11:56:42.000Z","size":289,"stargazers_count":18,"open_issues_count":4,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-29T12:49:31.283Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://devowl.io","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devowlio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-19T12:54:03.000Z","updated_at":"2024-10-15T13:30:04.000Z","dependencies_parsed_at":"2025-04-14T14:46:39.317Z","dependency_job_id":"d5a09511-1e77-4cca-baa7-80712885c16f","html_url":"https://github.com/devowlio/node-gitlab-ci","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/devowlio/node-gitlab-ci","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devowlio%2Fnode-gitlab-ci","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devowlio%2Fnode-gitlab-ci/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devowlio%2Fnode-gitlab-ci/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devowlio%2Fnode-gitlab-ci/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devowlio","download_url":"https://codeload.github.com/devowlio/node-gitlab-ci/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devowlio%2Fnode-gitlab-ci/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273431041,"owners_count":25104486,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T05:10:40.720Z","updated_at":"2025-10-08T09:17:08.335Z","avatar_url":"https://github.com/devowlio.png","language":"JavaScript","readme":"# node-gitlab-ci\n\n\u003cimg align=\"right\" src=\"https://assets.devowl.io/git/node-gitlab-ci/logo.png\" alt=\"node-gitlab-ci Logo\" height=\"180\" /\u003e\n\n**Create dynamic GitLab CI pipelines in JavaScript or TypeScript for each project. Reuse and inherit instructions and avoid duplicate code!**\n\nContinuous Integration (CI) and Continuous Deployment (CD) are fantastic concepts for process automation in software development. We love GitLab CI because it implements the concept in an integrated solution with powerful configuration capabilities. However, pipeline configurations are stored in a static `.gitlab-ci.yml` file.\n\nnode-gitlab-ci allows you to **develop pipeline configurations dynamically in TypeScript and avoid duplicates in the statements with programming concepts like inheritance or functions.** This way you can perfectly integrate e.g. monorepos with many similiar projects into the CI/CD.\n\n## Installation\n\nNavigate to your repository and install the package via `yarn` or `npm`:\n\n```bash\n# Yarn\nyarn add -D node-gitlab-ci\n\n# NPM\nnpm install --save-dev node-gitlab-ci\n```\n\nAfterwards, create a `.gitlab-ci.yml` file with the following content:\n\n```yml\n# CI pipeline is dynamically created through `node-gitlab-ci`, please checkout `.gitlab-ci.ts`!\n\nts config:\n    image: devowliode/node-gitlab-ci:latest\n    stage: build\n    script: node-gitlab-ci create-yml\n    artifacts:\n        paths:\n            - .gitlab-ci.ts.yml\n\ntrigger pipeline:\n    stage: test\n    trigger:\n        strategy: depend\n        include:\n            - artifact: .gitlab-ci.ts.yml\n              job: ts config\n```\n\nWhat does this statement do? The first job creates the `.gitlab-ci.ts.yml` file dynamically and the second job triggers the child pipeline. Learn more about this [in the GitLab documentation for child pipelines](https://docs.gitlab.com/ee/ci/parent_child_pipelines.html). It is recommended to add the `.gitlab-ci.ts.yml` file to your `.gitignore` file.\n\n## Usage\n\n### Your first `.gitlab-ci.ts`\n\nIt is a good practice to create a `.gitlab-ci.ts` in the root directory of your repository:\n\n```ts\nimport { Config, CreateConfigFunction } from \"node-gitlab-ci\";\n\nconst createConfig: CreateConfigFunction = async () =\u003e {\n    const config = new Config();\n\n    config.stages(\"build\", \"test\");\n\n    config.defaults({\n        image: \"alpine:latest\",\n    });\n\n    // Setting variables globally or per job\n    config.variable(\"DOCKER_DRIVER\", \"overlay2\");\n\n    // Run a job only in production branch\n    config.job(\n        \"only production\",\n        {\n            only: {\n                refs: [\"master\"],\n            },\n        },\n        true // Creates a hidden job (prefixed with a dot)\n    );\n\n    // Allows you to include further configurations by glob patterns\n    await config.include(__dirname, [\"devops/.gitlab/*.ts\"]);\n    await config.include(__dirname, [\"packages/*/devops/.gitlab/.gitlab-ci.ts\"]);\n\n    return config;\n};\n\nexport { createConfig };\n```\n\nThe complete GitLab CI [pipeline configuration](https://docs.gitlab.com/ee/ci/yaml/) is typed. Give it a try within your IDE and autocomplete!\n\n**Note**: You can not `import` (ES6) or `require` (ES5) all your installed modules. At the time of creating the dynamic pipeline, it is executed within [`devowliode/node-gitlab-ci`](https://hub.docker.com/r/devowliode/node-gitlab-ci) docker container and there are only the `node` modules like `fs`, `path`, ... available. Please read more about it below \"Use installed modules\".\n\n### Dry run locally\n\nIf you have successfully created the above file open a terminal session, navigate to your repository and:\n\n```bash\n# Yarn\nyarn node-gitlab-ci create-yml\n\n# NPM\nnpx node-gitlab-ci create-yml\n```\n\nA file `.gitlab-ci.ts.yml` will be created.\n\n### How `include` works\n\nThe most interesting part of `node-gitlab-ci` is how `include` works (for example you are using `yarn workspaces` or `lerna`). With `Config#include` you can dynamically include files by a glob pattern:\n\n```ts\n// Do not forget the await!\nawait config.include(__dirname, [\"packages/*/devops/.gitlab/.gitlab-ci.ts\"]);\n```\n\nThe extension file `packages/test/devops/.gitlab/.gitlab-ci.ts` must look like this:\n\n```ts\nimport { ExtendConfigFunction } from \"node-gitlab-ci\";\n\nconst extendConfig: ExtendConfigFunction = async (config) =\u003e {\n    // Create a job\n    config.job(/* [...] */);\n\n    // You can include further files\n    await config.include(__dirname, [\"./stage-*.ts\"]);\n};\n\nexport { extendConfig };\n```\n\n### How `extends` work\n\n`node-gitlab-ci` resolves automatically the [`extends`](https://docs.gitlab.com/ee/ci/yaml/#extends) keyword for you so you can fully profit from nested jobs without limitations (e. g. nested `extends` with same keys like `only` are no covered by GitLab CI). This is done a **deep merge** mechanism:\n\n```ts\nconfig.job(\n    \"only production\",\n    {\n        only: {\n            refs: [\"master\"],\n        },\n    },\n    true\n);\n\nconfig.extends(\".only production\", \"my-job\", {\n    script: [\"echo This job runs only in production!\"],\n});\n```\n\nYou can also extend from multiple jobs:\n\n```ts\nconfig.job(\n    \"common files changed\",\n    {\n        only: {\n            changes: [\"common/**/*\"],\n        },\n    },\n    true\n);\n\nconfig.extends([\".only production\", \".common files changed\"], \"my-job\", {\n    script: [\"echo This job runs only in production and when common files got changed!\"],\n});\n```\n\n### How `macro` works\n\nWith macros you can define callbacks and consume them with a set of parameters so you can dynamically create jobs with \"hard coded\" variables. The most excited use case is `only` in a monorepo:\n\n```ts\ntype EsLintMacroArgs = MacroArgs \u0026 {\n    prefix: string;\n};\n\nconfig.macro\u003cEsLintMacroArgs\u003e(\"lint eslint\", (self, { prefix }) =\u003e {\n    config.extends([`.common files changed`, `.lint eslint`], `${prefix} lint eslint`, {\n        only: {\n            changes: [`packages/${packageName}/{lib,scripts,test}/**/*.{js,jsx,tsx,ts}`],\n        },\n    });\n});\n```\n\nAnd in your package you can use this macro as follow:\n\n```ts\nconfig.from\u003cEsLintMacroArgs\u003e(\"lint eslint\", { prefix: \"utils\" });\n```\n\n### Interact with the GitLab REST API\n\nThis package comes with [`@gitbeaker/node`](https://github.com/jdalrymple/gitbeaker) bundled, so you can directly communicate with the [GitLab REST API](https://docs.gitlab.com/ee/api/api_resources.html). The API handler is brought to you with the following functionality:\n\n```typescript\n// List last 500 jobs in your project\nconfig.api.Jobs.all(1 /* your project id */, {\n    maxPages: 5,\n    perPage: 100,\n});\n```\n\n### Get changed files\n\nIf you need to detect changed file while child pipeline generation, you can use the following:\n\n```typescript\nconst changed = config.hasChanged(); // returns string[]\nconst specificFileHasChanged = config.hasChanged(/^packages\\/my-package\\//gm);\n```\n\n### Use installed modules\n\nAs mentioned previously you can not `import` or `require` any module. If you want to do so, you need to consider the following:\n\n-   Open a Pull Request or Issue [here](https://gitlab.com/devowlio/node-gitlab-ci) and ask to install the module globally in the image\n-   Create your own `Dockerfile` with the modules installed globally (e. g. `npm install --global fs-extra`), extended from [this](https://hub.docker.com/r/devowliode/node-gitlab-ci) dockerfile\n-   Modify the `ts config` job and install the modules globally or locally\n\n## Todo:\n\nThis repository is still in beta phase and the following things should be done:\n\n-   Use [`debug`](https://www.npmjs.com/package/debug) package instead of `console.log`\n-   Create GitLab CI with [`semantic-release`](https://www.npmjs.com/package/semantic-release) to automatically publish the package to npmjs.org\n-   Create and push docker image through CI instead of hub.docker.com\n-   Write Tests\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevowlio%2Fnode-gitlab-ci","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevowlio%2Fnode-gitlab-ci","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevowlio%2Fnode-gitlab-ci/lists"}