# Run and manage workflows

You can run and manage workflows from the environments view. Execute workflows manually, automatically via Git triggers, or on a cron schedule. Monitor workflow runs and roll back to previous deployments.

Select the environment that contains the workflow you want to manage from the environments view. You can run a workflow, or click the options button to view runs or edit the workflow.

## Run a workflow manually

You can run a workflow by clicking run in the workflow header.

1. Navigate to **Environments** in your project

2. Click on a workflow to open it

3. Click **Run** in the header

4. Configure the run (optional):
  
  
  
  - **Name**: Enter a descriptive name for this run
  
  - **Description**: Add details about what this release includes
  
  - **Git triggers**: Select branch and commit for each configured Git trigger
  
  - **Arguments**: Override default argument values

5. Click **Create**

![Running a workflow in the Northflank application](https://assets.northflank.com/documentation/v1/application/getting-started/set-up-environments/run-workflow.png)

If you do not enter a name for the run it will display a generated UUID, but you can edit the display name afterwards.

If the workflow contains build or deployment nodes you will be able to override the configured build or image to deploy, if required.

The workflow executes and you can monitor its progress in the run view.

## Use Git triggers to run workflows

You can [add Git triggers in the workflow settings](/v1/application/release/configure-workflows#add-triggers).

A trigger will run the workflow whenever a change to the specified repository is committed.

You can include:

- **Branch and pull request rules** to only trigger on commits to specific branches or pull requests

- **Path rules** to only trigger on changes to specific directories or files in a repository, or to ignore changes to specific directories or files

- **Commit message ignore flags** to skip runs for commits with messages that contain certain strings

You can use references to obtain the values of Git triggers in your workflow nodes.

## Use cron schedules to run workflows

Workflows can run automatically on a repeating schedule. This is useful for regular deployments, periodic maintenance tasks, or refreshing test environments.

To add a cron trigger:

1. Open your workflow

2. Click the plus sign or **Add trigger**

3. Select **Cron schedule** from the **Kind** dropdown

4. Enter a cron expression in the **Schedule** field (times are UTC, minimum interval is 10 minutes)

5. Save the trigger

6. Save the workflow

Each workflow can have one cron trigger.

For example, `0 * * * *` runs once an hour. Runs follow the workflow's [concurrency policy](configure-workflows#configure-workflow-settings).

Use the [trigger controls](configure-workflows#pause-triggers) to pause the schedule or all automatic triggers. Skipped scheduled runs are not replayed when you resume.

## Run a workflow using a webhook

> [!warning] Protect the webhook URL
>
> Treat the URL as a credential. Anyone with the URL can request a workflow run.

To start a workflow with a webhook:

1. Add a [Webhook trigger](configure-workflows#webhook-trigger).

2. Copy its Webhook URL.

3. Save the trigger.

4. Save the workflow.

5. Send a GET or POST request to the URL to start a workflow run.

Pass arguments in the URL query string for either method. Northflank ignores arguments in a POST body.

### Git trigger parameters

Webhook requests can supply Git trigger values, such as the branch and commit to build.

Use Trigger reference from the Git trigger form as the parameter prefix. Add a dot and the field name:

| Parameter | Value |
| --- | --- |
| `<git-trigger>.branch` | The branch name |
| `<git-trigger>.sha` | The commit SHA |
| `<git-trigger>.pullRequestId` | The ID of the pull request |
| `<git-trigger>.repoUrl` | The repository URL |

This request sets `frontend` to branch `feature` and `backend` to branch `develop`:

`https://webhooks.northflank.com/workflows/<TOKEN>?frontend.branch=feature&backend.branch=develop`

### Workflow name and description

Supply optional `name` and `description` query parameters to label the workflow run. If you omit `name`, Northflank shows the run ID.

### Other values

Other query parameters become workflow arguments. For example, `?foo=bar` makes `${args.foo}` resolve to `bar`.

Use query parameters for non-sensitive argument values. Store secrets in the workflow's [argument overrides](configure-workflows#configure-workflow-settings) instead of the URL.

### Pause or replace a webhook

Turn off Enable trigger to pause this webhook. Save the trigger and workflow. Pausing all workflow triggers also stops webhook runs. For a paused trigger created in the editor, requests return HTTP `404` and do not start a run.

To replace the URL, click Regenerate in the trigger form. Save the trigger and workflow. Update callers to use the new URL.

## View runs

The state of the current or most recent workflow run is indicated in the workflow header. This can be clicked to view the currently running workflow, or the list of previous runs.

### Workflow run statuses

Pending: the workflow is scheduled to run
Running: the workflow is currently running
Success: all of the nodes within the workflow completed successfully
Failed: some or all of the nodes within the workflow failed to complete successfully

### View workflow runs

Click on a workflow and click **view runs**.

This displays a list of previous and current workflow runs and their status. You can also see when the workflow was run, and when it was completed.

Open a run to inspect its nodes. When View diff is available, you can [inspect and download recorded resource changes](https://northflank.com/docs/v1/application/infrastructure-as-code/run-a-template#view-resource-changes).

### Node statuses

Pending: the node or workflow will run when previous steps are executed successfully
Running: the node or workflow is currently being executed
Waiting: the node is waiting for an action to be completed, will eventually timeout unless it receives a successful response
Retrying: the node has failed on previous runs, but is being executed again (up to 3 attempts)
Success: the node or workflow has completed successfully
Failed: the node or workflow has failed to execute, or exceeded 3 retries

## Re-run a workflow

You can re-run a previous workflow run to execute the same workflow with the same structure and arguments.

1. Navigate to **Environments** in your project

2. Click on a workflow

3. Click **View runs** in the sidebar

4. Click on the **Re-trigger** icon on the run you want to rerun

The workflow will execute again with the same configuration and arguments as the selected run. This allows you to re-execute a previous workflow without manually configuring it again.

## Next steps

- [Use canary rollouts: Release new versions progressively by shifting traffic between the stable and canary versions of your service.](/v1/application/release/canary-rollouts)
- [Set up preview blueprints: Create preview blueprints to automatically create preview environments for your branches and pull requests.](/v1/application/release/set-up-preview-blueprints)
- [Manage preview blueprints: Manage active previews, manually create test environments, and configure automatic cleanup.](/v1/application/release/manage-preview-blueprints)
- [Run migrations: Run database migrations and update your deployments simultaneously when you update your schema.](/v1/application/release/run-migrations)