TLDR: This is a TypeScript SDK for building TeamCity pipelines, instead of using Kotlin or XML.
import { Project } from "https://deno.land/x/teamcity-ts/mod.ts";
const myPipeline = new Project({ id: "MyPipeline" }, (p) => {
const host = p.Parameter({ name: "host", value: "1.1.1.1" });
p.Build({ id: "MyBuild" }, (b) => {
const count = b.Parameter({ name: "count", value: "3" });
b.CommandLineRunner({
id: "MyStep",
cmd: "ping",
args: ["-c", `${count}`, `${host}`],
executionPolicy: "default",
});
});
});HINT: This SDK targets Deno. Node.js support may be possible in the future...
This SDK is primarily concerned with the generation of the XML & does not provide any further infrastructure to get that XML into the right place at the right time.
Given the above example, it is up to you to do something like this:
const jobs = [];
for (const [filename, doc] of Object.entries(myPipeline.toXml())) {
jobs.push(Deno.writeTextFile(filename, doc.toString(true)));
}
await Promise.all(jobs);filename will always begin with .teamcity/ so assuming you tacked the above
on to the example & ran it from the root of your repo you would get the expected
outcome, that is the following files would be written:
./.teamcity/MyPipeline/project-config.xml./.teamcity/MyPipeline/buildTypes/MyBuild.xml
For a more complete solution checkout https://github.com/brad-jones/axe
- The TeamCity Kotlin DSL documentation has poor coverage.
- Outside of Java/Android circles, Kotlin as a language is not super well known.
- The tooling (VsCode Extension /
Language Server) for Kotlin
is buggy/not very mature.
- IMO Jetbrains IDEs are bloatware.
-
Through a painstaking process this TypeScript DSL is thoroughly documented & refers to the existing documentation for the TeamCity UI.
-
JavaScript & by extension TypeScript is one of the most ubiquitous languages on the planet. Other projects like the AWS CDK have successfully built similar, arguably much more complex, yet accessible DSLs on top of TypeScript.
-
The tooling for JavaScript/TypeScript is leaps and bounds ahead of the Kotlin developer experience.
read more: ./docs/dsl-design.md
I'll be up front right now that I haven't modeled every thing TeamCity provides, only the things that I think are going to matter most but the DSL has escape hatches, similar to the likes of the CDK, so if there is some obscure TeamCity feature that is not modeled, this DSL should still allow you define it in a type safe manner & not stand in your way.
read more: ./docs/extending.md
Legend:
- ✔️: This means the feature is fully modeled.
- 🧪: This means the feature also has a test case that proves it works with the latest version of TeamCity.
- ❌: This means the DSL provides zero support for this feature & you would have to model this yourself with an escape hatch.
| Construct | Status |
|---|---|
| Build | ✔️ |
| Build / Dependencies | ❌ |
| Build / Extensions / Agent Free Space | ✔️ |
| Build / Extensions / Assembly Info | ✔️ |
| Build / Extensions / Auto Merge | ✔️ |
| Build / Extensions / Commit Status Publishers / Atlassian Stash | ❌ |
| Build / Extensions / Commit Status Publishers / Bitbucket Cloud | ❌ |
| Build / Extensions / Commit Status Publishers / Gerrit | ❌ |
| Build / Extensions / Commit Status Publishers / Github | ✔️ |
| Build / Extensions / Commit Status Publishers / Gitlab | ❌ |
| Build / Extensions / Commit Status Publishers / Jetbrains Space | ❌ |
| Build / Extensions / Commit Status Publishers / Tfs (AzureDevOps) | ❌ |
| Build / Extensions / Commit Status Publishers / Upsource | ❌ |
| Build / Extensions / Docker Support | ✔️ |
| Build / Extensions / Failure on Message | ✔️ |
| Build / Extensions / Failure on Metric | ✔️ |
| Build / Extensions / File Content Replacer | ✔️ |
| Build / Extensions / Golang | ✔️ |
| Build / Extensions / Investigations Auto Assigner | ✔️ |
| Build / Extensions / Jira Cloud | ✔️ |
| Build / Extensions / Keep Rules | ✔️ |
| Build / Extensions / Notifiers / Email | ✔️ |
| Build / Extensions / Notifiers / Slack | ✔️ |
| Build / Extensions / Nuget Auth | ✔️ |
| Build / Extensions / Nuget Packages Indexer | ✔️ |
| Build / Extensions / Perfmon | ✔️ |
| Build / Extensions / PR Listeners / Bitbucket Cloud | ✔️ |
| Build / Extensions / PR Listeners / Bitbucket Server | ✔️ |
| Build / Extensions / PR Listeners / Github | ✔️ |
| Build / Extensions / PR Listeners / Gitlab | ✔️ |
| Build / Extensions / PR Listeners / Tfs (AzureDevOps) | ✔️ |
| Build / Extensions / Ruby Env Configurator | ✔️ |
| Build / Extensions / Shared Resources | ✔️ |
| Build / Extensions / SSH Agent | ✔️ |
| Build / Extensions / Swabra | ✔️ |
| Build / Extensions / Vcs Labeling | ✔️ |
| Build / Extensions / Xml Report Plugin | ✔️ |
| Build / Options | ✔️ |
| Build / Requirements | ✔️ |
| Build / Runners / Ant | ❌ |
| Build / Runners / Cargo | ❌ |
| Build / Runners / Command Line | ✔️ |
| Build / Runners / Conditions | ✔️ |
| Build / Runners / Docker | ❌ |
| Build / Runners / Docker Compose | ❌ |
| Build / Runners / Dotnet | ❌ |
| Build / Runners / Dotnet DupFinder | ❌ |
| Build / Runners / Dotnet Inspector | ❌ |
| Build / Runners / Duplicator | ❌ |
| Build / Runners / FTP | ❌ |
| Build / Runners / FxCop | ❌ |
| Build / Runners / Gradle | ❌ |
| Build / Runners / Inspection | ❌ |
| Build / Runners / JPS | ❌ |
| Build / Runners / Maven2 | ❌ |
| Build / Runners / MSpec | ❌ |
| Build / Runners / NAnt | ❌ |
| Build / Runners / Nuget Installer | ❌ |
| Build / Runners / Nuget Pack | ❌ |
| Build / Runners / Nuget Publish | ❌ |
| Build / Runners / NUnit | ❌ |
| Build / Runners / PowerShell | ❌ |
| Build / Runners / Python | ❌ |
| Build / Runners / Rake | ❌ |
| Build / Runners / SBT | ❌ |
| Build / Runners / SMB | ❌ |
| Build / Runners / SSH | ❌ |
| Build / Triggers / Cron | ✔️ |
| Build / Triggers / Dependency | ✔️ |
| Build / Triggers / Maven Artifact | ✔️ |
| Build / Triggers / Maven Snapshot | ✔️ |
| Build / Triggers / Nuget | ✔️ |
| Build / Triggers / Remote Branch | ✔️ |
| Build / Triggers / Retry | ✔️ |
| Build / Triggers / Vcs | ✔️ |
| Build / Vcs Settings | ✔️ |
| Cleanup | ✔️ |
| Parameter | ✔️ |
| Project | ✔️ |
| Project / Extensions / Issue Trackers / BitBucket | ✔️ |
| Project / Extensions / Issue Trackers / Bugzilla | ✔️ |
| Project / Extensions / Issue Trackers / Github | ✔️ |
| Project / Extensions / Issue Trackers / Jira | ✔️ |
| Project / Extensions / Issue Trackers / Tfs (AzureDevOps) | ✔️ |
| Project / Extensions / Issue Trackers / YouTrack | ✔️ |
| Project / Extensions / Keep Rules | ✔️ |
| Project / Extensions / OAuth Providers / Amazon Docker | ✔️ |
| Project / Extensions / OAuth Providers / BitBucket Cloud | ✔️ |
| Project / Extensions / OAuth Providers / Docker | ✔️ |
| Project / Extensions / OAuth Providers / Github | ✔️ |
| Project / Extensions / OAuth Providers / Gitlab | ✔️ |
| Project / Extensions / OAuth Providers / Jetbrains Space | ✔️ |
| Project / Extensions / OAuth Providers / Slack | ✔️ |
| Project / Extensions / OAuth Providers / Tfs (AzureDevOps) | ✔️ |
| Project / Extensions / Package Repositories / Nuget | ✔️ |
| Project / Extensions / Report Tabs / Build Report | ✔️ |
| Project / Extensions / Report Tabs / Project Report | ✔️ |
| Project / Extensions / Shared Resources | ✔️ |
| Project / Extensions / Versioned Settings | ✔️ |
| VCS Roots / Cvs | ❌ |
| VCS Roots / Git | ✔️ |
| VCS Roots / Mercurial | ❌ |
| VCS Roots / Perforce | ❌ |
| VCS Roots / Star Team | ❌ |
| VCS Roots / Svn | ❌ |
| VCS Roots / Tfs | ❌ |
A quick note about the missing build runners, I am of the strong belief that your pipeline should not rely on magic from the builder server. All functionality can be built in your pipeline on top of the Command Line Runner. All of those other types of build runners are magic IMO.
That said if I get PRs for the other build runners, I'm not going to reject them.