Content:
- Overview
- Access Control
- Creating a Configuration
- Selecting a Configuration
- Deleting a Configuration
- Navigating Hierarchical Configurations
- Types of Configuration Items:
Overview
ApartCI configurations are basic configuration management units, each containing one or more configuration items. Configuration items do not exist by themselves, they are always part of a configuration.
Configuration items are the basic units for controlling the ApartCI service. Several different types of configuration items target different ApartCI functional areas. Depending of their type some configuration items may actually be hierarchies of other configuration items.
The type of the single, top-most configuration item in such hierarchy dictates the type of the configuration. Offline configurations are just vehicles for managing configuration items and can have any type. Project configurations can also be live or simulation configurations, if they correspond to ApartCI projects, real or simulated, respectively.
Access Control
Access control is implemented at the ApartCI configuration level and applies to all configuration items contained in the respective configuration. A certain user can have read-write (RW), read-only (RO) or no access permission at all to a configuration, depending on:
- the user's role relative to the configuration: owner or not owner
- the type of access control specified when the configuration is created: private or public
- the type of user account: individual or organizational account
Only configuration owners have read-write (RW) permissions to it. By default the owner of a configuration is the user who creates the configuration. Ability for multiple users to share ownership or to transfer ownership between users is considered for future development.
Public configurations can be accessed in read-only (RO) mode by anyone, in some cases user login may not even be
required.
Private configurations owned by individual accounts are only accessible by their owners.
Private configurations owned by organizational accounts are accessible in read-only (RO) mode by all users of
the respective organization.
Support for team-based roles, with implicit and explicit inclusions and exclusions and a much more flexible access control is still in development.
Creating a Configuration
User login is required to create a configuration, in order to establish its default ownership.
Configurations can be created from scratch in the Create Config page by selecting the desired configuration type and pressing the Create New Config button.
A configuration can also be created in the Configuration page by pressing the Save Config Item As button from the Config Item Actions fieldset. The type and content of the new configuration will match those of the currently selected configuration item.
The new configuration's access control type - private or public - will have to be selected in a subsequent step.
Selecting a Configuration
In order to view or modify a configuration that configuration must first be selected, typically done in the Select Config page. An automatic redirection to this page happens if the Configuration menu is entered without a configuration being selected.
The Currently Selected Config Item fieldset displays a summary info about the configuration item currently selected, if any. Whenever a configuration is selected the top-most configuration item in the selected configuration becomes the currently selected configuration item.
The Currently Selected Project fieldset displays a summary info about the project currently
selected, live or simulated, if any.
Pressing the Select This Project button, visible if a project is currently selected, will
select the respective project's configuration as current configuration.
Pressing the Select Project or Select Another Project buttons, each visible
depending if a project is currently selected or not, will redirect to the project selection page.
The Offline Config Selection fieldset displays a selection filter and a table containing a list
of configurations matching the selection filter and meeting the access control permissions
of the logged in user.
If the user is not logged in the filter is automatically set to display only public configurations.
Selecting the radio button of one of the configurations from the table followed by pressing the
Select Offline Config button below the table will select the respective configuration as current.
The selection is persisted in the browser session until it is overwritten or until the user logs out.
The currently selected configuration can be overwritten by:
- a new offline configuration being selected
- a project's configuration when the respective project is selected in the Select Project page
- a project configuration being simulated when the respective simulation is selected in the Select Simulation page
Deleting a Configuration
An offline configuration can be deleted by selecting its corresponding radio button in the Offline Config Selection fieldset form the Select Config page then pressing the Delete Selected Offline Config button below the table. Of course, the user must be logged in and have read-write (RW) permissions to it.
A live project configuration is deleted when the respective project is deleted.
A simulation project configuration is deleted when the respective simulation is deleted.
Navigating Hierarchical Configurations
ApartCI configurations typically contain multiple configuration items, hierarchically structured.
To view or modify a configuration item one must first navigate the hierarchy and make the respective item become
the currently selected one in the Configuration page.
An example of such page is illustrated below:
The first line of the Currently Selected Config Item fieldset indicates the type of the configuration item - a Stage in this example (marked as #1) and a summary information about the configuration itself (marked as #2). The configuration item type is also indicated in the Item Configuration Details fieldset title (marked as #3).
If the item is not the top-most item in the configuration then the ancestry path of the item is displayed as a list of URLs (marked as #4) which can be used to navigate towards its ancestor items.
Each type of child items supported by a configuration item is displayed as a separate fieldset inside the
Item Configuration Details fieldset. In this example Stage a configuration items supported Stage QA
Step child child configuration items (marked as #5)
To select as current any of the existing, displayed child configuration items press the corresponding
Configure button (marked as #6).
To create new child configuration items press the corresponding Add <child item type> button -
Add Step in this example (marked as #7). The newly created child configuration item will automatically
be selected.
Types of Configuration Items
There are several types of configuration items:
Configuring a Project
Project configuration items contain:
- the project's name. It is not used alone for identification, so it doesn't have to be unique. A project will also have an automatically assigned unique identifier.
- the project's VCS repository set configuration item.
- one stage configuration item for the pre-commit verification stage, mandatory.
- one or more stage configuration items for preliminary verification stage(s), optional.
- one stage configuration item for the post-commit verification stage, optional.
Configuring a VCS Repository Set
VCS repository set configuration items contain:
- the repository set's name. If the item is a child of another VCS repository set configuration item then it has to be unique across all repositories and repository sets having the same parent configuration item.
- the repository set's branch - the default branch name used by all child repositories and/or
repository sets if their configuration items does not have a branch configured to override this default
branch name.
If the currently selected VCS repository set is a child of another VCS repository set the inherited default branch name is also displayed. In such case the branch name is optional. If configured it will override the inherited default branch name.
Regardless of the branch name being configured or inherited it becomes the default branch name used by all child repositories and/or repository sets without a configured branch name. - one or more VCS repository set configuration items for child VCS repository set(s), optional.
- one or more VCS repository configuration items for child VCS repositories, optional.
Configuring a VCS Repository
VCS repository configuration items contain:
- the repository's name. If the item is a child of another VCS repository set configuration item then it has to be unique across all repositories and repository sets having the same parent configuration item.
- the repository's branch, optional - if one is configured it will override the default branch name inherited from an ancestor VCS repository set configuration item.
Configuring a Stage
Stage configuration items contain:
- the stage's name - a description string used for informational purposes only.
- one or more Stage QA Step configuration items.
The procedure is the same regardless of the stage type: preliminary, pre-commit or post-commit, what differs is just the list of QA steps and their inter-dependencies, which represent the stage's QA flow.
Configuring a Stage QA Step
Stage QA step configuration items contain:
- the step's type. The type must be selected before the rest of the step configuration can
continue as different types may require different configurations.
The supported step types are:- ws_create - for steps preparing workspaces for QA steps of build type
- build - for steps building images or other artifacts, typically in workspaces created by ws_create steps
- test - for steps executing various testing, typically on built artifacts
- the step's name - a description string used for informational purposes only.
- one or more QA step artifact configuration items produced by this step, optional.
- one or more QA step artifacts required by this step, optional. These can only be check-box selected from the list displayed, which contains all artifacts produced by all other QA steps already configured in the same stage.
Configuring a QA Step Artifact
QA step artifact configuration items contain:
- the artifact's type. The type must be selected before the rest of the artifact
configuration can continue as different types may require different configurations.
The supported artifact types are:- ws_id - for workspace identifier artifacts
- image - for artifacts produced by a QA step of build type
- the stage's name - a description string used for informational purposes only.
- one or more Stage QA Step configuration items.