Build Forge Concepts and Terminology

Users and roles

To access Build Forge, users need to have a user object set up for them. In production systems, this is done by configuring Build Forge to access an identity management system, LDAP.

Build Forge uses an authorization system to control user access to all objects. Access group objects contain lists of permissions. A user belongs to one or more access groups.

You can create your own access groups or modify the ones provided. The access groups defined in the system are:

• Build Engineer – defines processes (creates projects and steps)
• System Manager – administers servers and other system-wide features
• Security – administers users, access, and security
• Developer – helps develop processes, runs jobs, views results
• Operator – copies projects, runs jobs, views results
• Guest – copies projects, runs jobs, views results

Servers

A server object defines a place where projects and steps can run. Projects and steps can use the same server or select one independently.

Server objects represent hosts where work is performed. The host must be running a Build Forge agent to receive the work from the system and return results.

Other objects are related to servers and need to be set up before defining projects and steps:

• Server Authentications: a server authentication stores login information for the server to use to access the host specified by the server. A server authentication must be created before creating the server that uses it. In the server definition, choose the server authentication from the list of all server authentications defined in the system.
• Collectors: a collector object gathers specified properties of a server. The data is stored in a manifest. Servers have a default set of properties assigned. These built-in properties include information about the host architecture, network connections, and resources (CPU, memory, load). You can add other properties by defining collector objects. A collector must be created before adding it to the server. In the server definition, choose the collector from the list of all collectors defined in the system.
• Selectors: a selector object defines how a server is selected for use by a project or step. A selector must be created before adding it to the project that uses it. In the project definition, choose the selector from the list of all selectors defined in the system.
• Environments: an environment object is a set of variables that can be used by a step. During a job, the variables are set on the server host before the step is run. Environments can be associated with server objects, project objects, and step objects. When the same variable is set to different values in different environments, an inheritance scheme determines which value is used. An environment must be created before adding it to a server, project, or step. In those object definitions, choose the environment from the list of all environments defined in the system.

Environments

An environment is a set of variables. Environments can be specified for server, project, and step objects. When a step runs, environments set at each of those objects are combined to provide variables for the step to use. See About environments.

Variables can be changed as a step runs. See Changing variable values during step execution.) The scope of the change can be local to the step, local to the project, or permanent (the variable is changed in the stored environment.

Predefined system variables are available as well as variables you define.

Projects

A project defines work to be done in a process. When a project is started, it runs as a job.

The work to be done is contained in the list of steps.

Other objects are related to projects:

• Selectors: a selector determines where the project will be started. If a selector is not specified for the project, then it cannot run independently and is called a library. The selector must already be defined to assign it to a job.
• Environments: an environment object is a set of variables that can be used by a step. During a job, the variables are set on the server host before the step is run. Environments can be associated with server objects, project objects, and step objects. An inheritance scheme determines which values are used if the same variable is set to different values. An environment must be created before creating the server, project, or step that uses it. In those object definitions, choose the environment from the list of all environments defined in the system.
• Notification templates: a notification template defines how to send out notifications about job activity (job start, job pass, job fail, others). A notification object defines who to notify through access groups. You specify the location of your SMTP server in a system setting.
• Classes: a class object is used to group projects for maintenance purposes. Typically classes are used to purge or archive completed jobs periodically. All jobs that have run using the project are affected by the class.
• Adaptors: an adaptor defines an integration with an external system, typically a source code management system. Several sample templates are provided as a starting point. You need to configure them further to manage the connection and perform specified actions in the system.
• Adaptor links: an adaptor link defines the relationship between an adaptor and the project that uses it.

Steps

A step defines the smallest unit of work to be done. (See About steps.) Its key component is its Command property, which includes a command to be run on the selected server.

The Command property can also be used to run dot commands. Dot commands are commands that run on the process engine and provide additional functionality.

Other objects are related to projects:

• Selectors: a step can have its own selector. If not specified it uses the selector of its project.
• Environments: a step can have its own environment. The environments provided by the server, the project, and the step are combined. By default they are applied in that order, so that any variables defined by the step’s environment take precedence over definitions of the same variable. Precedence can be controlled in system settings.
• Log Filters: a step can be assigned a log filter in its Result property. A log filter object is used to specify conditions that indicate if the step passes or fails. When running a Perl engine, you use regular expressions to scan the log for a particular pattern. When running a Java engine, you also use regular expressions to scan the log for a particular pattern. Normally the exit status of the command is used, but log filters provide an alternate means. A log filter must be created before specifying it in a step. In the Result property for the step, you choose the log filter from the list of all log filters defined in the system.
• Notification templates: a notification template defines how to send out notifications about step activity (step start, step pass, step fail, others). A notification object defines who to notify through access groups. You specify the location of your SMTP server in a system setting.
• Build Catalyst: a step can run rafmake, the key utility in Build Catalyst. Build Catalyst provides the means to accelerate make-based builds. Build Catalyst must be installed on the same host where the make builds are run, in addition to a Build Forge agent.

Jobs

A job is a running project. When the job is started, the process engine queues it and then runs it. You can check its status in the Jobs panel. When it completes, the following information is available:

• Results: you can review the results of all steps by opening the job. You can also open a running job to monitor its progress.
• Step log: the step log records extensive information about how a step was run, including information about the manifest and environment settings as well as execution results. Click the step results link in the Results page to view the log.
• Bill of Materials: the Bill of Materials (BOM) contains information about job steps and step manifests. You can use the .bom dot command to format additional information for the BOM and write data to it. You can use the .scan dot command to add baselines and checkpoints to the BOM.

You can cancel and restart jobs. You can add projects to the Schedule to have them run at scheduled times.