---
metadata:
- name: generator
content: Diplodoc Platform v5.50.6
alternate:
- https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/ci-cd.md
- https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/ci-cd.md
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt
# Configuring CI/CD in a SourceCraft repository
{% note tip %}
You can set up and view repository configurations in the SourceCraft interface under **Repository settings** in the **Configurations** section. Learn more in [this article](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/configuration-edit.md).
{% endnote %}
SourceCraft has an in-built [CI/CD workflow](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md) management mechanism.
The CI/CD configuration is set up for a particular repository and stored in a file named `.sourcecraft/ci.yaml`.
General format of the `.sourcecraft/ci.yaml` configuration file:
```yaml
on:
pull_request:
- workflows: []
filter:
source_branches: []
target_branches: []
paths: []
push:
- workflows: []
filter:
branches: []
paths: []
- workflows: []
filter:
tags: []
schedule:
- workflows: []
interval:
description:
- workflows: []
cron: ""
description:
workflows:
:
tasks:
- name:
cubes:
- name:
image:
script:
-
...
```
The configuration may include the following elements:
* [Trigger events](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md) (`on` section)
* [Workflows](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md) (`workflows` section)
* [Jobs](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.md) (`tasks` section)
* [Cubes](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md) (`cubes` section)
* [Service connections](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tokens.md) (`tokens` section)
* [Environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/env.md) (`env` section)
{% note tip %}
The `.sourcecraft/ci.yaml` file supports file structure output as well as search for declarations and element usages. For more information, see [Navigating and searching by code in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/code-navigation.md).
{% endnote %}
You can either use nested structure for configuration elements or mark them up as separate sections.
{% cut "Example of CI/CD configuration marked up as separate sections" %}
```yaml
on:
pull_request:
- workflows: my-test-workflow
filter:
source_branches: ["**", "!test**"]
target_branches: "main"
workflows:
my-test-workflow:
tasks:
- my-test-task
tasks:
- name: my-test-task
cubes:
- name: my-test-cube
uses: hello-cube
cubes:
- name: hello-cube
script:
- echo "Hello, world!"
```
{% endcut %}
The configuration file supports [secrets](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#secrets). Learn more in [Using the value of a secret in CI/CD](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/secrets.md#use-secret-in-ci-cd).
CI/CD workflows are run by trigger events. Such events may include pushing changes to a remote repository branch (`push`), creating a pull request (`pull_request`), or running a scheduled execution (`schedule`).
You can configure different workflows for different events. You can also configure triggers for specific branches or paths in the repository.
For a description of the configuration elements, see the [CI/CD reference](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/index.md).
You can configure CI/CD [when creating a new repository](#when-creating) or in an [existing one](#existing).
## Configuring CI/CD when creating a repository {#when-creating}
1. Open the SourceCraft [home page](https://sourcecraft.dev).
1. In the left-hand panel, click **Create repository**.
1. In the window that opens, set the repository parameters.
1. Under **Configuration**, select **Add a CI/CD template**.
1. Select the CI/CD configuration template from the **YAML** drop-down list:
* `Docker`
* `HelloWorld`
* `Java`
* `NodeJS`
* `Python`
For the contents of the templates, see [Examples](#examples).
1. Click **Create repository**.
The root of the created repository will contain the `.sourcecraft/ci.yaml` file with the CI/CD configuration template.
## Configuring CI/CD in an existing repository {#existing}
1. Clone the repository:
1. [Install Git](https://git-scm.com/downloads).
1. Open the SourceCraft [home page](https://sourcecraft.dev).
1. On the **Home** tab, under **Your craftspace**, navigate to **Repositories** and select your repository.
Also, you can open any public repository.
1. In the top-right corner of the repository page, click **Clone**.
1. From the **HTTPS** or **SSH** field, copy the repository cloning link.
Depending on the cloning connection protocol, different domains are used:
#|
|| **Protocol** | **Domain** | **Cloning link** ||
|| HTTPS | `git.sourcecraft.dev` | `https://git@git.sourcecraft.dev//.git` ||
|| SSH | `ssh.sourcecraft.dev` | `ssh://ssh.sourcecraft.dev//.git` ||
|#
1. In the terminal, run this command:
```bash
git clone
```
{% cut "Example of a command for cloning a repository with SourceCraft documentation" %}
```bash
git clone https://git@git.sourcecraft.dev/sourcecraft/documentation.git
```
{% endcut %}
{% note warning %}
To clone a [private or internal repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#repos), authenticate with a [personal access token (PAT)](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md) or [SSH key](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/ssh.md).
{% endnote %}
1. Go to your cloned repository:
```bash
cd
```
1. Generate a CI/CD `.sourcecraft/ci.yaml` configuration file as described in the [CI/CD reference](#examples) or use the templates in [Examples](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/index.md).
1. Add the CI/CD configuration file to the `git` index, commit, and push the changes to the `main` branch:
```bash
git add .sourcecraft/ci.yaml
git commit -m "Added CI/CD configuration"
git push -u origin main
```
## Checking CI/CD workflow execution {#check-ci-cd}
1. Depending on the settings specified in `.sourcecraft/ci.yaml`, run a trigger event.
1. Check CI/CD workflow execution:
1. Under **Code** on the repository page, go to **CI/CD**.
1. Select a running workflow.
1. The page that opens will display all workflow tasks, cubes (task steps), as well as statuses and execution results.
## Examples {#examples}
{% list tabs %}
Open the config.json file. It already contains a basic VM configuration, but you can customize it:
- Hello World
```yaml
# This basic workflow
# will help you get started with SourceCraft CI/CD
# Configuring a trigger event to execute a workflow
on:
# Executing a workflow triggered by sending changes to the remote repository's main branch
# or by creating a pull request for the main branch
pull_request:
- workflows: [sample-workflow]
filter:
source_branches: ["**", "!test**"]
target_branches: "main"
push:
- workflows: [sample-workflow]
filter:
branches: ["main"]
workflows:
sample-workflow:
tasks:
- name: sample-task
cubes:
# Starting a set of commands
- name: sample-cube1
image: docker.io/library/node
script:
- echo Hello, world!
- name: sample-cube2
script:
- echo Add other cubes to build,
- echo test, and deploy your project.
```
- Docker
```yaml
on:
push:
- workflows: build-workflow
filter:
branches: ["main"]
workflows:
build-workflow:
tasks:
- build-task
tasks:
- name: build-task
env:
IMAGE_URI: dockerhub_account/hello-world
cubes:
- name: docker-build
script:
- docker build . --file Dockerfile --tag $IMAGE_URI:$(date +%s)
# Optional: sending a Docker image to a registry
# Provide to the cube the credentials for authentication in the registry,
# e.g., DockerHub or Yandex Container Registry
# - name: push-dockerhub
# env:
# USER: username
# PAT: personal_access_token
# script:
# - echo $PAT | docker login --username $USER --password-stdin
# - docker push $IMAGE_URI
```
To test the CI\CD process, send a commit with `Dockerfile` to the `main` branch:
```dockerfile
FROM alpine
CMD ["echo", "Hello World!!"]
```
- Python
```yaml
on:
push:
- workflows: [sample-workflow]
filter:
branches: ["main"]
workflows:
sample-workflow:
tasks:
- name: sample-task
cubes:
- name: sample-cube1
image: docker.io/library/python
script:
- python -m pip install --upgrade pip
- if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
```
Add data specific to testing Python applications to the `.gitignore` file.
{% cut ".gitignore example" %}
```text
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
.pybuilder/
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .python-version
# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock
# UV
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
#uv.lock
# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock
# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/latest/usage/project/#working-with-version-control
.pdm.toml
.pdm-python
.pdm-build/
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# pytype static type analyzer
.pytype/
# Cython debug symbols
cython_debug/
# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/
# PyPI configuration file
.pypirc
```
{% endcut %}
To test the CI\CD process, send a commit with a `main.py` file to the `main` branch:
```python
print('Hello SourceCraft')
print('Hello SourceCraft')
for i in range(10):
print(i)
# input
hi = input()
print(hi)
```
- Node.js
```yaml
on:
push:
- workflows: build-workflow
filter:
branches: ["main"]
workflows:
build-workflow:
tasks:
- build-task
tasks:
- name: build-task
cubes:
- name: build-npm
image: docker.io/library/node
script:
- npm ci
- npm run build --if-present
- npm test
```
To test the CI\CD process, send a commit with the following files to the `main` branch:
* `index.js`:
```js
//index.js
function helloNpm() {
return "hello SourceCraft CI/CD"
}
module.exports = helloNpm
```
* `package.json`:
```json
{
"name": "sourcecraft-samples-nodejs",
"version": "1.0.0",
"description": "Sample for SourceCraft CI/CD",
"license": "MIT",
"author": "SourceCraft Team",
"type": "commonjs",
"main": "index.js",
"scripts": {
"test": "echo \"test passed\""
}
}
```
* `package-lock.json`:
```json
{
"name": "sourcecraft-samples-nodejs",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "sourcecraft-samples-nodejs",
"version": "1.0.0",
"license": "MIT"
}
}
}
```
- Java
```yaml
# This workflow will build a Java project using Maven
on:
push:
- workflows: publish-package-workflow
filter:
branches: ["main"]
workflows:
publish-package-workflow:
settings:
max_cube_duration: 10m
tasks:
- build-publish-task
tasks:
- name: build-publish-task
cubes:
- name: setup-jdk-maven
script:
- sudo apt install openjdk-21-jdk -y
- sudo apt install maven -y
- java --version
- mvn --version
- name: test
script:
- echo 'test'
- name: package
script:
- mvn package
# Optional: Export the artifact named
# `sourcecraft-sample-maven-1.0-SNAPSHOT.jar` from the target directory.
# You can download this artifact from the cube in the CI/CD section
#artifacts:
# paths:
# - target/sourcecraft-sample-maven-1.0-SNAPSHOT.jar
```
Add data specific to testing Java applications to the `.gitignore` file.
{% cut ".gitignore example" %}
```text
##############################
## Java
##############################
.mtj.tmp/
*.class
*.jar
*.war
*.ear
*.nar
hs_err_pid*
replay_pid*
##############################
## Maven
##############################
target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
pom.xml.next
pom.xml.bak
release.properties
dependency-reduced-pom.xml
buildNumber.properties
.mvn/timing.properties
.mvn/wrapper/maven-wrapper.jar
##############################
## Gradle
##############################
bin/
build/
.gradle
.gradletasknamecache
gradle-app.setting
!gradle-wrapper.jar
##############################
## IntelliJ
##############################
out/
.idea/
.idea_modules/
*.iml
*.ipr
*.iws
##############################
## Eclipse
##############################
.settings/
bin/
tmp/
.metadata
.classpath
.project
*.tmp
*.bak
*.swp
*~.nib
local.properties
.loadpath
.factorypath
##############################
## NetBeans
##############################
nbproject/private/
build/
nbbuild/
dist/
nbdist/
nbactions.xml
nb-configuration.xml
##############################
## Visual Studio Code
##############################
.vscode/
.code-workspace
##############################
## OS X
##############################
.DS_Store
##############################
## Miscellaneous
##############################
*.log
```
{% endcut %}
To test the CI\CD process, send a commit with the following files to the `main` branch:
* `pom.xml`:
```xml
4.0.0com.mycompany.appsourcecraft-sample-maven1.0-SNAPSHOTbondarevsky-mavenhttp://www.example.comUTF-817org.junitjunit-bom5.11.0pomimportorg.junit.jupiterjunit-jupiter-apitestorg.junit.jupiterjunit-jupiter-paramstestmaven-clean-plugin3.4.0maven-resources-plugin3.3.1maven-compiler-plugin3.13.0maven-surefire-plugin3.3.0maven-jar-plugin3.4.2maven-install-plugin3.1.2maven-deploy-plugin3.1.2maven-site-plugin3.12.1maven-project-info-reports-plugin3.6.1
```
* `src/test/java/com/mycompany/app/AppTest.java`:
```java
package com.mycompany.app;
import static org.junit.jupiter.api.Assertions.assertTrue;
import org.junit.jupiter.api.Test;
/**
* Unit test for simple App.
*/
public class AppTest {
/**
* Rigorous Test :-)
*/
@Test
public void shouldAnswerWithTrue() {
assertTrue(true);
}
}
```
* `src/main/java/com/mycompany/app/App.java`:
```java
package com.mycompany.app;
/**
* Hello world!
*/
public class App {
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
```
{% endlist %}
#### Useful links {#see-also}
* [Repository templates](https://sourcecraft.dev/sourcecraft/repos)
* [Getting started with SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/quickstart.md)
* [Continuous integration and continuous deployment in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md)
* [CI/CD reference](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/index.md)
* [Configuring CI/CD with Yandex Cloud Functions](https://sourcecraft.dev/portal/docs/en/sourcecraft/tutorials/ci-cd-sourcecraft-functions.md)
* [Starting a workflow manually in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/run-workflow-manually.md)
* [Configuring a webhook in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/webhooks.md)