Projects

Introduction

Projects are the core resource at Torch. Each repository can have a single project and can be easily created by following few simple steps. You may only create projects from source control providers that are connected to your account. To connect source control providers, either log in with the provider or connect from the Source Control tab in your account's settings page.

Source Control Provider Permissions

It's important to know that since Torch runs a few tasks on the source control provider to make sure project is properly configured, it requires an administrator permissions on the repository. When creating a project, if the project is not listed, your connected source control account most likely doesn't have appropriate permissions.

If Torch cannot configure the project, it will display the appopriate error message in the Recent Activity panel in your Torch dashboard.

Builds and commits

When project is created, Torch automatically creates a webhook and a deploy key for that project in the project's source control provider. This allows Torch to listen when new commits are pushed to the project.

Once a commit is pushed, Torch will automatically initiate a new build for that commit. When a build starts, Torch will boot the container, clone the repository and prepare the environment. This happens while the build is in the Provisioning phase and it generally takes around 40 seconds. As soon as Torch provisions a container, it will begin running build steps that have been configured for the project. Torch will also create a status on the source control provider to indicate that the commit is currently running.

Once a build ends, Torch will update the commit status to reflect the status of the build.

Building Pull Requests

It's important to know that Torch does not build any pull requests, but only new commits that have been pushed to the repository.

You may watch the output for each build step in the pipeline in real-time.

YAML Configuration

Project configuration details, such as the build pipeline, PHP version and database engine is modified from the project's settings in the Torch UI, but most of the configurations can be done via the YAML configuration in a torchci.yml file placed in the root of the project.

When new commit is pushed, Torch will try to find the YAML configuration file. If the file cannot be found, Torch will build the project using settings defined in the Torch UI.

Debugging

For easier debugging, Torch displays the entire YAML configuration file in the build details page. If YAML syntax is invalid, Torch will fail the build and display the appropriate error message in build details page.

Notifications

Projects can be configured to send a Slack and email notifications when builds end, depending on the build's end status. For example, you may configure Torch to send the email notification once a build fails. You may also configure multiple notification channels for multiple events.

Creating notification channels can be done through the project's settings in Torch UI.

SSH key

When you create a project, Torch automatically generates a pair of SSH keys for your project. Every time you push a commit, project's private SSH key is stored in the container. The advantage to this is that you can store project's public SSH key in your production server to gain SSH access to the server right from the container. This allows you to execute shell scripts on a remote machine from project's build pipeline.

To download the public SSH key for the project, click the 'Download Key' button in project settings. You may also generate a new pair of keys right from the project settings by clicking the 'Rotate Key' button.

Composer Cache

Installing Composer & NPM dependencies can be a slow process, but most of the time it only downloads the changes. That's why we designed Torch to cache the project's Composer & NPM dependencies after each successful build. Next time you push a commit, those dependencies will install much faster thus resulting in a faster build.

Clearing Cache

Sometimes, when there's a lot of changes in the composer.lock file, installing Composer dependencies may fail. If that happens, you may clear the Composer & NPM cache from the project settings in the Torch UI, by clicking the 'Clear Cache' button. This will ensure that the next commit will always clean install Composer and NPM dependencies.

Status Badge

To display the current status of the project, use the URL below to generate a status badge SVG based on the latest build. You may use this to display the badge in the repository's README.md file.

By default, Torch will display the status for the master branch. To change that, add the branch parameter to the URL.

# HTML
https://torchci.com/projects/{projectId}/status?branch=master

# Different branch
https://torchci.com/projects/{projectId}/status?branch=my-new-feature

# Markdown
![Torch CI](https://torchci.com/projects/{projectId}/status?branch=master)