Concourse is primarily driven from the command-line; there is no GUI config wizard.
So, the first step to getting started with Concourse is to install the
fly CLI tool. You can download
fly from any Concourse installation. There are download links for common platforms in the bottom right hand corner of the main page.
Throughout the Concourse documentation we'll stick to the long-form name of every command and flag. Once you've learned what the commands do, you may want to consult
fly -h to learn the short forms.
The first thing you'll want to do is authenticate with your target. This is done with the
fly login command. This is also useful to save targets under a more convenient alias, so you don't have to type out the URL all the time:
login command serves double duty: it authenticates with a given endpoint, and saves it under a more convenient name. The name and token are stored in
~/.flyrc (though you shouldn't really edit the file manually).
So, to log in to a team
my-team an endpoint served at
https://ci.example.com and save it as the more convenient name
example, you would run:
$ fly --target example login --team-name my-team \ --concourse-url https://ci.example.com
login command will see which authentication methods are available for the specified team and prompt you to choose one. For basic auth, it will ask your username and password and use them to acquire a token. For OAuth, it will give you a link to click, and after you've gone through the OAuth flow it will print an OAuth token on the page that you can then then copy and paste into the prompt.
Note that if no authentication methods are configured,
fly will acquire a token without any prompting. You can then use the alias like normal.
In any case, a token is saved in your
~/.flyrc, which will expire after one day.
If your Concourse uses SSL but does not have a certificate signed by a trusted CA, you can use the
--ca-cert flag so that
fly can trust the connection, like so:
$ fly -t example login -c https://ci.example.com --ca-cert ./ca.crt
This will read the value out of the file
./ca.crt and save it into
~/.flyrc so you don't have to pass it on every
After you've logged in you can use
--target example (or
-t example for short) to run a command against the saved target
example. For eample,
fly -t example builds will list the last few builds on the
example Concourse instance.
-t flag is intentionally stateless and must be explicitly added to each command. This reduces the risk of accidentally running a command against the wrong environment when you have multiple targets defined.
To see what targets are currently known to
$ fly targets
This will show each target's name, URL, and when its token expires.
To check your current authentication status with a given target, run:
$ fly -t example status
This will let you know if the token has expired.
There are cases when you would like to remove all evidence of a particular target. This is achieved by the
logout command. There are two variants of this command, one to get rid of a specific target, and another to remove all targets from the
To remove a specific target run:
$ fly -t example logout
To remove all targets run:
$ fly logout -a
Note: These two variations are mutually exclusive. If the target parameter
-t and all parameter
-a are both specified, an error will occur.
Occasionally we add additional features to
fly or make changes to the communiction between it and Concourse's API server. To make sure you're running the latest and greatest version that works with the Concourse you are targeting we provide a command called
sync that will update your local
fly. It can be used like so:
$ fly -t example sync
fly command will also warn you if it notices that your CLI version is out of sync with the server.