How to use the command 'fly' (with examples)

The fly command-line tool is an integral piece of the Concourse CI/CD system, which facilitates building, testing, and deploying applications. The tool allows users to interact with their Concourse server, manage CI/CD pipelines, and carry out various automation tasks effortlessly. fly is designed to bridge the user’s local environment and the Concourse CI system, enabling seamless CI operations through the terminal.

Authenticate with and save concourse target

Code:

fly --target target_name login --team-name team_name -c https://ci.example.com

Motivation:

Before you can interact with your Concourse CI server using fly, you need to authenticate yourself. This command establishes a connection between your local environment and the Concourse server, enabling subsequent operations on specified pipelines or tasks under a particular team.

Explanation:

• --target target_name: Specifies a name for this particular Concourse server instance so you can easily reference it in future commands.
• login: Initiates the authentication process.
• --team-name team_name: Specifies the team within the Concourse server you want to log into. Teams are a way to organize resources and permissions.
• -c https://ci.example.com: The URL endpoint of the Concourse server you are targeting for login.

Example Output:

target saved
logging in to team 'team_name'
target saved

List targets

Code:

fly targets

Motivation:

Listing targets is a helpful operation to understand which Concourse servers your local fly client is authenticated against. Particularly useful in environments where you have multiple Concourse servers and need to switch between them frequently.

Explanation:

• targets: A command that displays all the Concourse instances saved in your fly configuration, detailing the target name, URL, and the team currently authenticated.

Example Output:

name          url                     team
target_name   https://ci.example.com  team_name

List pipelines

Code:

fly -t target_name pipelines

Motivation:

Once authenticated, you might be interested in viewing all the pipelines configured for your team. This command is essential for gaining insight into available workflows and their status on the specified target server.

Explanation:

• -t target_name: Tells fly which target server to use for this command.
• pipelines: Lists all defined pipelines on the given target for the authenticated team, along with their status (paused or unpaused).

Example Output:

name           paused   public
pipeline_name  yes      no

Upload or update a pipeline

Code:

fly -t target_name set-pipeline --config pipeline.yml --pipeline pipeline_name

Motivation:

This operation is crucial when you have updated a pipeline configuration or need to introduce a new one into your Concourse server. By uploading or updating pipelines, you ensure that your CI/CD workflows execute the defined tasks correctly.

Explanation:

• -t target_name: Directs the command to the specified Concourse target.
• set-pipeline: The action to upload or update a pipeline’s configuration.
• --config pipeline.yml: Specifies the file containing your pipeline configuration.
• --pipeline pipeline_name: Names the pipeline you are setting or updating on the Concourse server.

Example Output:

pipeline created!

Unpause pipeline

Code:

fly -t target_name unpause-pipeline --pipeline pipeline_name

Motivation:

Pipelines can be paused for various reasons, such as maintenance or incomplete setups. Unpausing is necessary to begin the execution of jobs once you’re ready, ensuring that your development workflow continues uninterrupted.

Explanation:

• -t target_name: Selects the target Concourse instance.
• unpause-pipeline: Specifies the action to take; in this case, to unpause a previously paused pipeline.
• --pipeline pipeline_name: Identifies the specific pipeline that should be unpaused.

Example Output:

unpaused 'pipeline_name'

Show pipeline configuration

Code:

fly -t target_name get-pipeline --pipeline pipeline_name

Motivation:

Viewing the configuration of an existing pipeline is critical for debugging, verifying settings, or simply understanding how the pipeline is structured. This command helps you retrieve and review the current pipeline setup.

Explanation:

• -t target_name: References the Concourse target you want to inspect.
• get-pipeline: Fetches the configuration details of a specified pipeline.
• --pipeline pipeline_name: Identifies which pipeline’s configuration to display.

Example Output:

jobs:
- name: job_name
  plan:
  - task: task_name
    config:
      platform: linux

Update local copy of fly

Code:

fly -t target_name sync

Motivation:

Keeping your fly CLI up to date is vital for compatibility and access to the latest features or commands provided by Concourse updates. Synchronizing ensures that you always operate with the latest potential command set.

Explanation:

• -t target_name: Indicates which Concourse instance’s latest fly is being fetched.
• sync: Commands fly to update itself by downloading the latest version from the target Concourse server.

Example Output:

downloading fly version 6.7.3
successfully synced

Destroy pipeline

Code:

fly -t target_name destroy-pipeline --pipeline pipeline_name

Motivation:

In scenarios where a pipeline is no longer needed, perhaps due to replaced workflows or decommissioned projects, it’s prudent to clean up and remove unnecessary pipelines to maintain your Concourse server’s cleanliness and organization.

Explanation:

• -t target_name: Points fly to the appropriate Concourse target.
• destroy-pipeline: Clearly instructs fly to remove a specified pipeline.
• --pipeline pipeline_name: Denotes which pipeline should be destroyed.

Example Output:

! destroying pipeline 'pipeline_name'

Conclusion:

In conclusion, the fly CLI is an indispensable tool for managing and interacting with Concourse CI servers from the command line. This guide has gone through key use cases, providing complete command syntax, the rationale behind each operation, and sample outputs you might expect. Whether you’re managing pipeline lifecycles or ensuring your fly CLI is up-to-date, mastering these commands streamlines your CI/CD processes significantly.