# Create a pipeline
Source: https://docs.infraista.com/en/developer-tools/pipelines/create-a-pipeline



A new pipeline takes four steps: connect a repository, choose a starting point, review the YAML and
choose where the file lives. The file is saved as `.infraista/pipeline.yml` in the repository.

**Before you start:** you need permission to manage pipelines (Owners, Admins and Developers by
default). Managed runners are billed per minute after the monthly free minutes; see
[Runners and billing](/en/developer-tools/pipelines/runners-and-billing).

## 1. Connect a repository [#1-connect-a-repository]

Go to **Pipelines** and select **New pipeline**. Under **Git provider**, pick a tab:

| Provider                | How you connect                                                                                                   | Repositories you see                        |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| **GitHub**              | **Connect GitHub** installs the Infraista app on the account or organization you choose                           | The ones you gave the app access to         |
| **GitLab**              | **Connect GitLab** opens gitlab.com's consent screen; select **Authorize**                                        | Projects where you're a Maintainer or Owner |
| **GitLab self-managed** | Enter your **Instance address** (https, reachable from the internet) and an **Access token** with the `api` scope | Projects the token can reach                |
| **Bitbucket**           | **Connect Bitbucket** opens Bitbucket's consent screen                                                            | Repositories where you're an Admin          |

For self-managed GitLab, a group access token (role Maintainer) is best: it keeps working when people
leave.

<Shot name="developer-tools/pipelines/new" alt="New pipeline, step 1: the Git provider tabs and the Connect repository panel" />

Then select the repository. Infraista looks at its root files (Dockerfile, package.json and so on) and
for an existing pipeline file. Missing a GitHub repository? Select **Change which repositories
Infraista can read in your GitHub settings**.

When the pipeline is created, Infraista adds a webhook to the repository so pushes and pull requests
start runs (on GitHub, the app's own webhook does this).

## 2. Choose a starting point [#2-choose-a-starting-point]

* **Use the pipeline file in this repo** if `.infraista/pipeline.yml` already exists.
* **Start from a template**: plain YAML you can change later. A **Suggested** template matches what
  was found in the repository.

| Template                                             | What it does                                                                                                          |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Node.js**, **Python**, **Go**                      | Install, lint or vet, and test                                                                                        |
| **Docker image**                                     | Build the repository's Dockerfile and push the image (to your Container Registry, with no secrets, when you have one) |
| **Deploy to a server over SSH**                      | On every push to the default branch, copy the code to your server and run your deploy commands                        |
| **Build an image, deploy it over SSH**               | Build and push the image, then pull and run it on your server                                                         |
| **Build an image, run it as containers on a server** | Run the image as an API on a port, a worker and a scheduler, with migrations in between                               |
| **Build and deploy per branch**                      | main to production, staging and dev to their own servers                                                              |
| **Deploy with a deploy agent**                       | For a server Infraista can't reach over SSH                                                                           |
| **Test, then build**                                 | Parallel checks in a test stage, then a build stage that waits for them                                               |
| **Start from scratch**                               | One job that checks out the code and runs a command                                                                   |

The image templates that use your Container Registry appear once you have one.

If the template builds a Docker image and the repository has no Dockerfile, you can have
[Dockerfile Studio](/en/developer-tools/dockerfile-studio) write one and include it in the same pull
request.

## 3. Review the YAML [#3-review-the-yaml]

The file opens in the editor, in **Visual** (stages as columns and jobs as cards) or **YAML** view.
It's checked as you type, with errors on their lines. Under **Key settings**:

* **Pipeline name**: letters, digits, dots, dashes and underscores. It's shown on commits as
  `infraista/<name>`.
* **Runner size**: the default for jobs that don't name one.
* When it runs: **Run on push to**, **Pull requests into**, and **Nightly at 02:00 UTC**.

The [pipeline file reference](/en/developer-tools/pipelines/pipeline-file-reference) explains every key.

## 4. Choose where the file lives [#4-choose-where-the-file-lives]

| Option                                                         | What happens                                                                                                                     |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Test first, commit later** (recommended)                     | Nothing is written to the repository yet. Run the file from the editor with **Test run**, and commit it from there when it works |
| **Commit to the repo on a new branch and open a pull request** | Your team reviews the file like any change. The first run starts on the pull request                                             |
| **Commit directly to** the default branch                      | Fastest. The pipeline runs right away if the file runs on pushes to that branch                                                  |

Select **Create pipeline** (or **Save and open the editor** for a draft).

## Check that it worked [#check-that-it-worked]

The pipeline appears under **Pipelines**. Its first run starts with the next push or pull request the
file matches, or select **Run pipeline** to start one now. See
[Runs and logs](/en/developer-tools/pipelines/runs-and-logs).

## Test changes before committing [#test-changes-before-committing]

Open the pipeline's **Editor** tab, change the file and select **Test run**. It runs the editor's text
on the latest commit of a branch, without committing anything:

* By default deploy steps don't deploy: each checks that its target exists and is reachable instead,
  image builds don't push, and jobs don't use environments (so no approvals).
* Turn deploys on to run the file exactly as written.

Test runs don't report a status on the commit. Saving from the editor commits to the branch or opens a
pull request, like step 4.

## If something goes wrong [#if-something-goes-wrong]

* **"That GitHub installation is already connected to another Infraista account."** Each installation
  belongs to one organization. Install the app on another account, or disconnect it in the other
  organization first.
* **A self-managed GitLab instance isn't accepted.** It must use https and be reachable from the
  internet.
* **No runs start.** Check the triggers in the file match the branch you pushed to, and that the commit
  message doesn't contain a skip marker such as `[skip ci]`. See
  [Triggers](/en/developer-tools/pipelines/triggers).

## Related [#related]

* [Pipeline file reference](/en/developer-tools/pipelines/pipeline-file-reference)
* [Triggers](/en/developer-tools/pipelines/triggers)
* [Secrets and variables](/en/developer-tools/pipelines/secrets-and-variables)